[Java] Run a CICS-Java application-(4) Spring Boot app

17 minute read

Introduction

CICS TS for z/OS supports running Liberty, so you can run Java EE applications on CICS. With support for Spring Boot from CICS TS V5.3, Spring Boot applications can now also run on CICS (with Liberty on CICS). Running on CICS means that JCICS, which uses the functions of CICS, can be used, so Web applications that call existing CICS programs, Web applications that access CICS-managed VSAM and TSQ, etc. run only on CICS. Furthermore, it means that you can develop it using the Spring Boot framework.

In this article, I will run a sample of the CICS-SpringBoot app provided on GitHub below. cics-java-liberty-springboot-jcics

Both Maven and Gradle can be used to manage the build, but I will use Gradle here.

Related article

Run CICS-Java application-(1) Running simple sample application Run CICS-Java application-(2) Maven build management Run CICS-Java application-(3) Build management by Gradle Move CICS-Java application-(4) Spring Boot application

Advance preparation

*If Gradle manages the deployment, the destination CICS must be under CICSplex management.

Development environment (PC)

Suitable Java EE development environment

Please use those that can develop Java EE applications such as Eclipse and VS Code. Since I will use the sample as it is, I do not need to edit the source, so I do not need to use it, but normally I will use some development environment. It would be nice to be able to work with Gradle, git, etc. If you want to use CICS Explorer together, use Eclipse.

CICS Explorer

This is also not required, but it can be used to check the resource definition of CICS. Refer to the following and download and set up an Eclipse-based tool called CICS Explorer. Reference: Downloading and starting CICS Explorer *This tool is free for CICS users.

Gradle

Follow the steps below to install. Installing Gradle Basically, just unzip the downloaded one and pass it through the path.

As a prerequisite, Java 8 or later is required.

c:\>java -version
java version "1.8.0_144"
Java(TM) SE Runtime Environment (build 1.8.0_144-b01)
Java HotSpot(TM) 64-Bit Server VM (build 25.144-b01, mixed mode)

Download the latest version of Gradle V6.5 from the following (gradle-6.5.zip). Releases

Extract to an appropriate directory. (Here (c:\x\Gradle\gradle-6.5) Add the extracted bin (C:\x\Gradle\gradle-6.5\bin) to your PATH.

Confirmation

c:\>gradle -v

- ------------------------------------------------- ----------
Gradle 6.5
- ------------------------------------------------- ----------

Build time: 2020-06-02 20:46:21 UTC
Revision: a27f41e4ae5e8a41ab9b19f8dd6d86d7b384dad4

Kotlin: 1.3.72
Groovy: 2.5.11
Ant: Apache Ant(TM) version 1.10.7 compiled on September 1 2019
JVM: 1.8.0_144 (Oracle Corporation 25.144-b01)
OS: Windows 10 10.0 amd64

This is OK.

git

Since you will be using the sample provided on gitHub, install git as well. The setup method etc. is omitted because it is rolling around there.

c:\>git --version
git version 2.21.0.windows.1

Execution environment (z/OS, CICS)

Prepare a CICS region to run the sample. We will use a region named CT56B4A1 under CICSplex management. Add a resource called JVMServer to run the Java application. This time, since the sample (JavaEE application) for CICS-Liberty is used, create JVMServer for Liberty.

JVM profile

Prepare a JVM profile on USS. (The properties related to JVMServer are effectively specified in a file on this USS. The JVMSERVER resource definition points to the file name of this JVM profile.) A sample is provided so you can copy it and use it.

Create a directory called /var/cicsts/cicsts56/CT56B4A1/JVMProfiles and copy /usr/lpp/cicsts/cicsts56/JVMProfiles/DFHOSGI.jvmprofile (sample definition for OSGi located under the CICS installation directory) into it. To do. Customize as appropriate for your environment.

DFHWLP.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=56441
- Dcom.ibm.cics.jvmserver.wlp.server.https.port=56451
- 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 property file is placed in the SIT parameter “JVMPROFILEDIR”.

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

Restart the region for the changes to take effect.

JVMServer definition

Prepare the JVMSERVER resource definition. Copy the JVMSERVER definition “DFHWLP” in the product-provided DFH$WLP group and install it.

OBJECT CHARACTERISTICS CICS RELEASE = 0730
 CEDA View JVmserver( DFHWLP)
  JVmserver: DFHWLP
  Group: TAGGRP
  DEScription: CICS JVM server to run WLP samples
  Status: Enabled Enabled | Disabled
  Jvmprofile :DFHWLP (Mixed Case
  Lerunopts: DFHAXRO
  Threadlimit: 015 1-256
 DEFINITION SIGNATURE
  DEFinetime: 06/04/20 16:20:21CHANGETime: 06/04/20 16:20:21
  CHANGEUsrid: CICSUSER
  CHANGEAGEnt :CSDApi CSDApi | CSDBatch
  CHANGEAGRel: 0730

*Jvmprofile: DFHWLP, but this means that the file DFHWLP.jvmprofile under the directory specified in JVMPROFILEDIR of SIT is used as the JVM property file.

It is OK if CEMT I JVM SERVER shows Enable.

I JVMS
STATUS: RESULTS-OVERTYPE TO MODIFY
 Jvm(DFHWLP )Ena Prf(DFHWLP )Ler(DFHAXRO)
    Threadc(005) Threadl( 015) Cur(48314096)

change server.xml

In the sample execution procedure this time, the procedure up to Deploy is manual rather than automatic, so add the settings for that.

If you specify -Dcom.ibm.cics.jvmserver.wlp.autoconfigure=true in the JVM profile, Liberty will be automatically configured. Once the JVMSERVER definition is installed, Liberty will be configured under the work directory (work/CT56B4A1/DFHWLP/wlp/usr/servers/defaultServer). Modify server.xml under this directory to do the following.

server.xml


...
<applicationMonitor dropins="dropins" dropinsEnabled="true" pollingRate="5s" updateTrigger="polled"/>
...

In this way, specify dropinsEnabled=”true”, updateTrigger=”polled”. This will automatically detect the war placed in the dropins directory. Create a dropins directory in the same directory (.../work/CT56B4A1/DFHWLP/wlp/usr/servers/defaultServer/dropins).

Restart JVMServer after making changes.

CICS Bundle Deployment API

You must have set up the CICS Bundle Deployment API, which is now provided by CICS TS V5.6. (Not required for manual deployment of sample procedure) This feature was added for application deployment as one of the REST-based management APIs called CMCI. Set up CMCI on the WUI server that manages the target CICS region and specify the parameters for the CICS Bundle Deployment API in the properties of the CMCI JVM server. Reference: How it works: CICS bundle deployment API

The minimum required settings are as follows. Create a directory for placing Bundle files on USS. Here it is /var/cicsts/cicsts56/bundles. Set the following parameters in the JVM profile (EYUCMCIJ.jvmprofile) for CMCI JVM Server of WUI. -Dcom.ibm.cics.jvmserver.cmci.bundles.dir=/var/cicsts/cicsts56/bundles

Sample operation check (1) / Manual deployment

First of all, try to move it according to the procedure provided on github. Reference: cics-java-liberty-springboot-jcics

Clone locally

Create an appropriate directory and clone https://github.com/cicsdev/cics-java-liberty-springboot-jcics.git to your local PC.

c:\y\workspace\cicsts56>git clone https://github.com/cicsdev/cics-java-liberty-springboot-jcics.git
Cloning into'cics-java-liberty-springboot-jcics'...
remote: Enumerating objects: 67, done.
remote: Counting objects: 100% (67/67), done.
remote: Compressing objects: 100% (43/43), done.
remote: Total 67 (delta 12), reused 56 (delta 7), pack-reused 0
Unpacking objects: 100% (67/67), done.

Understanding the file structure

Go to the directory “cics-java-liberty-springboot-jcics” and take a look at the file structure.

c:\y\workspace\cicsts56\cics-java-liberty-springboot-jcics>tree /f /a
Folder Path List: Volume Windows
Volume serial number is 1866-E2FC
C:.
| .classpath
| .gitignore
| .project
| build.gradle
| gradlew
| gradlew.bat
| LICENSE
| mvnw
| mvnw.cmd
| pom.xml
| README.md
| settings.gradle
|
+---.mvn
| \---wrapper
| maven-wrapper.jar
| maven-wrapper.properties
| MavenWrapperDownloader.java
|
+---.settings
| org.eclipse.buildship.core.prefs
| org.eclipse.wst.common.component
| org.eclipse.wst.common.project.facet.core.xml
|
+---gradle
| \---wrapper
| gradle-wrapper.jar
| gradle-wrapper.properties
|
\---src
    \---main
        +---java
        | \---com
        | \---ibm
        | \---cicsdev
        | \---springboot
        | \---jcics
        | Application.java
        | BrowseTSQController.java
        | DeleteTSQController.java
        | ServletInitializer.java
        | TSQInfoController.java
        | WriteTSQController.java
        |
        \---webapp
            \---WEB-INF
                    ibm-web-ext.xml
                    web.xml

It is a one-shot project of the application part. The CICS Bundle project is not included. It seems to support both Maven and Gradle, but here we use Gradle.

Check/edit contents

There are some sources, but let’s take a look at WriteTSQController.java, for example. Just watch this.

WriteTSQController.java


/* 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 *//*                                                                        */

package com.ibm.cicsdev.springboot.jcics;

import java.io.IOException;
import java.io.UnsupportedEncodingException;

import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RequestParam;
import org.springframework.web.bind.annotation.RestController;

import com.ibm.cics.server.CicsConditionException;
import com.ibm.cics.server.TSQ;

@RestController
public class WriteTSQController {

 /**
  * The @GetMapping annotation ensures that HTTP GET requests are mapped to the annotated method. 
  * @throws IOException 
  **/
 @GetMapping("/writeTSQs")
 public String writeTSQs(@RequestParam(value = "tsqName", defaultValue = "ANNE") String tsqName,
   @RequestParam(value = "tsqContent", defaultValue = "Spring greetings from CICS!") String tsqContent) {

  String response = "";

  // Write to the TSQ
  try {
   response = writeTSQ(tsqName, tsqContent);
  } catch ( CicsConditionException | UnsupportedEncodingException e) {

   // Print the stack trace
   e.printStackTrace();

   // Return useful information to the user when meeting errors
   return "Oops! Unexpected CICS condition exception: "  + e.getMessage() + ". Please check stderr for details.";
  }
  return response;
 }

 /**
  * A method to write a record to a TSQ
  * 
  * @param tsqName, the name of the TSQ to be written to
  * @param record, the data to be written to the TSQ
  * @return, the result of the write 
  * @throws UnsupportedEncodingException 
  * @throws CicsConditionException    
  */
 private String writeTSQ(String tsqName, String record) throws CicsConditionException, UnsupportedEncodingException{
  
  // Construct the TSQ object
  TSQ tsqQ = new TSQ();
  tsqQ.setName(tsqName);

  // the result of writing an item to the TSQ
  String result = "";

  // write the record to the TSQ
  tsqQ.writeString(record);  
  result = "Record written to TSQ " + tsqName + ".";

  // return the result to the calling servlet
  return result;
 }
}

JCICSのTSQクラスを使ってTSQにデータを書き込むだけの単純なアプリです。URI /writeTSQsのquery parameterでtsqName, tsqContentを受け取り、tsqNameで指定されたTSQにtsqContentで指定された値を書き込むようになっています。

ibm-web-ext.xmlで、context-rootを確認しておきます。これも確認のみ。

ibm-web-ext.xml


<?xml version="1.0" encoding="UTF-8"?>
<web-ext
 xmlns="http://websphere.ibm.com/xml/ns/javaee"
 xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
 xsi:schemaLocation="http://websphere.ibm.com/xml/ns/javaee http://websphere.ibm.com/xml/ns/javaee/ibm-web-ext_1_0.xsd"
 version="1.0">

 <reload-interval value="3"/>
 <context-root uri="cics-java-liberty-springboot-jcics-ding" />
 <enable-directory-browsing value="false"/>
 <enable-file-serving value="true"/>
 <enable-reloading value="true"/>
 <enable-serving-servlets-by-class-name value="false" />

</web-ext>

build.gradleを開いて、依存関係の指定をターゲットのCICSのバージョンに合わせて編集します。ここではCICS TS V5.6をターゲットとするので、以下のように修正します。

build.gradle


...
compileOnly enforcedPlatform("com.ibm.cics:com.ibm.cics.ts.bom:5.6-20200609123739")
...

指定する値は以下から判断することになります。 参考:IBM CICS TS BOM

ビルド

以下のコマンドでビルドします。

c:\y\workspace\cicsts56\cics-java-liberty-springboot-jcics>gradlew.bat clean bootwar
Downloading https://services.gradle.org/distributions/gradle-6.5-bin.zip
.........10%..........20%..........30%..........40%.........50%..........60%..........70%..........80%.........90%..........100%
Starting a Gradle Daemon (subsequent builds will be faster)

BUILD SUCCESSFUL in 1m 35s
3 actionable tasks: 2 executed, 1 up-to-date

成功すると、以下のWARが作成されます。 build/libs/cics-java-liberty-springboot-jcics-0.1.0.war

デプロイ

このサンプルの手順では手動でWARをデプロイするようになっているので、一旦それでやってみます。

先に作成しておいた、dropinsディレクトリにバイナリモードで上のWARファイルを転送します。 これで自動でアプリが認識されるはずです。 (この方式の場合、BUNDLE定義は使いません)

アプリ稼働確認

ブラウザから、ターゲットのLibertyがListenしているhost:portに対して以下のようなリクエストを投げてみます。 http://etp1:56441/cics-java-liberty-springboot-jcics-ding/writeTSQs?tsqName=SPGJCICS&tsqContent=ILOVECICS SPGJCICSという名前のTSQにILOVECICSというメッセージを投入することになります。 うまくいけば、TSQにデータが書き込まれるので、CICS端末からCEBRで確認してみます。 image.png きちんとデータが投入されていることが確認できました。

サンプルの稼働確認(2) / Gradleによるデプロイ

さて、上の手順だとデプロイが手動になってしまいスマートでは無いので、DeployまでGradleで実施できるようCICS Bundleプロジェクトを追加してみます。

注意!: 上の手順で手動デプロイを試した場合は、アプリがバッティングするのでdropinsディレクトリのwarを削除し、JVMSERVERを再起動しておいてください。

Gradleマルチプロジェクト作成

CICS Bundleプロジェクトを追加し、サンプルで提供されているWARとまとめるための親のプロジェクトを作成します。

親プロジェクト

まず、親となるプロジェクトのディレクトリ cics-springboot01というディレクトリを作成します。そこでgradle wrapperを実行しておきます。

c:\y\workspace\cicsts56\cics-springboot01>gradle wrapper

Deprecated Gradle features were used in this build, making it incompatible with Gradle 7.0.
Use '--warning-mode all' to show the individual deprecation warnings.See https://docs.gradle.org/6.5/userguide/command_line_interface.html#sec:command_line_warnings

BUILD SUCCESSFUL in 6s
1 actionable task: 1 executed
c:\y\workspace\cicsts56\cics-springboot01>tree /a /f
Folder Path List: Volume Windows
Volume serial number is 1866-E2FC
C:.
| gradlew
| gradlew.bat
|
+---.gradle
| +---6.5
| | | gc.properties
| | |
| | +---executionHistory
| | | executionHistory.bin
| | | executionHistory.lock
| | |
| | +---fileChanges
| | | last-build.bin
| | |
| | +---fileHashes
| | | fileHashes.bin
| | | fileHashes.lock
| | |
| | \---vcsMetadata-1
| +---buildOutputCleanup
| | buildOutputCleanup.lock
| | cache.properties
| | outputFiles.bin
| |
| +---checksums
| | checksums.lock
| |
| \---vcs-1
| gc.properties
|
\---gradle
    \---wrapper
            gradle-wrapper.jar
            gradle-wrapper.properties

Create build.gradle and setting.gradle here as follows.

build.gradle


group'com.ibm.cicsdev.springboot'
version '1.0.0'

setting.gradle


rootProject.name ='cics-springboot01'
include'cics-java-liberty-springboot-jcics'
include'cics-springboot-bundle04'

Child project (1) / for WAR

It uses exactly what is provided in the sample. Follow the steps above to clone cics-java-liberty-springboot-jcics with git clone under the parent project directory. Then modify the compileOnly line in build.gradle to match your target CICS version.

Child project (2) / for CICS Bundle

This will build build.gradle for the bundle, referring to the previous article. Reference: Run a CICS-Java application-(3) Build management by Gradle

Create a directory named cics-springboot-bundle04 under the parent project directory, and create build.gradle as shown below. The directory name should match the name specified in the parent’s setting.gradle.

build.gradle


plugins {
    id'com.ibm.cics.bundle' version '1.0.0'
}

group'com.ibm.cicsdev.springboot'
version '1.0.0'

repositories {
    mavenCentral()
}

cicsBundle {
    build {
        defaultJVMServer ='DFHWLP' // (1)JVMSERVER name
    }
    deploy {
        cicsplex ='C73PLX' // (2) CICSplex name to which the target CICS region belongs
        region ='CT56B4A1' // (3) Target CICS region name
        bunddef ='SPBBUNDL' // (4) Bundle definition resource name defined in the target CICS region
        csdgroup ='TAGGRP' // (5) CSD group name to which the bundle definition of (4) belongs
        url ='http://etp1:56002' // (6) WCI CMCI URL
        username ='TAG' // (7) With the user used when issuing the Deployment API by CMCI
        password ='xxxxxxxx' // password
        //caution: uncomment the line below to disable TLS/SSL checking for certificates
        //insecure = true
    }
}

dependencies {
    cicsBundlePart project(path:':cics-java-liberty-springboot-jcics', configuration:'archives')
}

The final structure is like this.

c:\y\workspace\cicsts56\cics-springboot01>tree /a /f
Folder Path List: Volume Windows
Volume serial number is 1866-E2FC
C:.
| build.gradle
| gradlew
| gradlew.bat
| settings.gradle
|

...

+---cics-java-liberty-springboot-jcics
| | .classpath
| | .gitignore
| | .project
| | build.gradle
| | build_original.gradle
| | gradlew
| | gradlew.bat
| | LICENSE
| | mvnw
| | mvnw.cmd
| | pom.xml
| | README.md
| | settings.gradle
| |
| +---.gradle
| | +---6.5
| | | | gc.properties
| | | |
| | | +---executionHistory
| | | | executionHistory.bin
| | | | executionHistory.lock
| | | |
| | | +---fileChanges
| | | | last-build.bin
| | | |
| | | +---fileContent
| | | | fileContent.lock
| | | |
| | | +---fileHashes
| | | | fileHashes.bin
| | | | fileHashes.lock
| | | |
| | | +---javaCompile
| | | | classAnalysis.bin
| | | | javaCompile.lock
| | | | taskHistory.bin
| | | |
| | | \---vcsMetadata-1
| | +---buildOutputCleanup
| | | buildOutputCleanup.lock
| | | cache.properties
| | | outputFiles.bin
| | |
| | +---checksums
| | | checksums.lock
| | | md5-checksums.bin
| | | sha1-checksums.bin
| | |
| | \---vcs-1
| | gc.properties
| |
| +---.mvn
| | \---wrapper
| | maven-wrapper.jar
| | maven-wrapper.properties
| | MavenWrapperDownloader.java
| |
| +---.settings
| | org.eclipse.buildship.core.prefs
| | org.eclipse.wst.common.component
| | org.eclipse.wst.common.project.facet.core.xml
| |
| +---gradle
| | \---wrapper
| | gradle-wrapper.jar
| | gradle-wrapper.properties
| |
| \---src
| \---main
| +---java
| | \---com
| | \---ibm
| | \---cicsdev
| | \---springboot
| | \---jcics
| | Application.java| | BrowseTSQController.java
| | DeleteTSQController.java
| | ServletInitializer.java
| | TSQInfoController.java
| | WriteTSQController.java
| |
| \---webapp
| \---WEB-INF
| ibm-web-ext.xml
| web.xml
|
+---cics-springboot-bundle04
| build.gradle
|
\---gradle
    \---wrapper
            gradle-wrapper.jar
            gradle-wrapper.properties

BUNDLE definition creation

Create a bundle definition according to the contents specified in build.gradle above.

OBJECT CHARACTERISTICS CICS RELEASE = 0730
 CEDA View Bundle( SPBBUNDL)
  Bundle: SPBBUNDL
  Group: TAGGRP
  DEScription: CICS-SpringBoot-Sample
  Status: Enabled Enabled | Disabled
  BUndledir: /var/cicsts/cicsts56/bundles/cics-springboot-bundle04_1.0.
  (Mixed Case): 0
                 :
                 :
                 :
  BAsescope:
  (Mixed Case):
                 :
                 :
                 :
 DEFINITION SIGNATURE
  DEFinetime: 07/07/20 17:03:45
  CHANGETime: 07/07/20 17:03:57
                                                                              
                                                    SYSID=B4A1 APPLID=CT56B4A1
                              DSN=CICSTS56.CICS.DFHCSD

Specify CSD group (5), BUNDLE definition name (4), and BUNDLEDIR based on the project directory name and version information values. *We will not install it yet

Build/deploy execution

Build Spring Boot WAR as follows.

c:\y\workspace\cicsts56\cics-springboot01>gradlew bootWar

BUILD SUCCESSFUL in 6s
2 actionable tasks: 2 executed

Then build and deploy the CICS Bundle.

c:\y\workspace\cicsts56\cics-springboot01>gradlew deployCICSBundle

> Task :cics-springboot-bundle04:buildCICSBundle
Adding Java-based bundle parts from'cicsBundlePart' dependency configuration
Adding Java-based bundle part:'C:\y\workspace\cicsts56\cics-springboot01\cics-java-liberty-springboot-jcics\build\libs\cics-java-liberty-springboot-jcics-0.1.0.war '
Adding non-Java-based bundle parts from'src/main/resources'

> Task :cics-springboot-bundle04:deployCICSBundle
Task deployCICSBundle

BUILD SUCCESSFUL in 29s
4 actionable tasks: 3 executed, 1 up-to-date

It is OK if you can confirm that the bundle and bundle parts are ENABLED from CICS Explorer. image.png

I was able to deploy it with Gradle!

By the way, if you look at the messages.log of Liberty, you can see that the Spring Boot application has started.

[7/7/20 9:20:35:354 GMT] 000000d0 LogService-87-com.ibm.cics.wlp.bundlepart.impl I CWWKE0703I: [com.ibm.cics.wlp.bundlepart.impl] [CICSLibertyBundlepartControllerImpl] @Info: installBundlepart()-cics-java
- liberty-springboot-jcics-0.1.0, SPBBUNDL, 2, /var/cicsts/cicsts56/bundles/cics-springboot-bundle04_1.0.0/, 1.0.0, 206F2740000001E9,,, -1, -1, -1, CSD_API
[7/7/20 9:20:35:376 GMT] 000000d1 LogService-87-com.ibm.cics.wlp.bundlepart.impl I CWWKE0703I: [com.ibm.cics.wlp.bundlepart.impl] [CICSLibertyBundlepartControllerImpl] @Info: enableBundlepart()-3549516473

[7/7/20 9:20:36:381 GMT] 00000055 com.ibm.ws.app.manager.AppMessageHelper I CWWKZ0018I: Starting application cics-java-liberty-springboot-jcics-0.1.0.
[7/7/20 9:20:36:382 GMT] 00000055 bm.ws.app.manager.war.internal.WARDeployedAppInfoFactoryImpl I CWWKZ0136I: The cics-java-liberty-springboot-jcics-0.1.0 application is using the archive file at the /var/cicsts/cicsts56/C
T56B4A1/work/CT56B4A1/DFHWLP/wlp/usr/servers/defaultServer/installedApps/cics-java-liberty-springboot-jcics-0.1.0.war location.
[7/7/20 9:20:36:723 GMT] 00000055 com.ibm.ws.webcontainer.osgi.webapp.WebGroup I SRVE0169I: Loading Web Module: cics-java-liberty-springboot-jcics.[7/7/20 9:20:36:723 GMT] 00000055 com.ibm.ws.webcontainer                                      I SRVE0250I: Web Module cics-java-liberty-springboot-jcics has been bound to default_host.
[7/7/20 9:20:36:723 GMT] 00000055 com.ibm.ws.http.internal.VirtualHostImpl                     A CWWKT0016I: Web application available (default_host): http://etp1:56441/cics-java-liberty-springboot-jcics-ding/
[7/7/20 9:20:36:725 GMT] 00000055 com.ibm.ws.app.manager.AppMessageHelper                      A CWWKZ0003I: The application cics-java-liberty-springboot-jcics-0.1.0 updated in 0.344 seconds.
[7/7/20 9:20:36:733 GMT] 0000004d com.ibm.ws.webcontainer.osgi.mbeans.PluginGenerator          I SRVE9103I: A configuration file for a web server plugin was automatically generated for this server at /var/cicsts/cicsts56/
CT56B4A1/work/CT56B4A1/DFHWLP/wlp/usr/servers/defaultServer/logs/state/plugin-cfg.xml.
[7/7/20 9:20:36:800 GMT] 0000004b com.ibm.ws.session.WASSessionCore                            I SESN0176I: A new session context will be created for application key default_host/cics-java-liberty-springboot-jcics-ding
[7/7/20 9:20:36:801 GMT] 0000004b com.ibm.ws.util                                              I SESN0172I: The session manager is using the Java default SecureRandom implementation for session ID generation.
[7/7/20 9:20:37:064 GMT] 0000004b com.ibm.ws.webcontainer.webapp                               I SRVE0292I: Servlet Message - [cics-java-liberty-springboot-jcics-0.1.0]:.2 Spring WebApplicationInitializers detected on cla
sspath
[7/7/20 9:20:37:973 GMT] 0000004b SystemOut                                                    O   .   ____          _            __ _ _
[7/7/20 9:20:37:973 GMT] 0000004b SystemOut                                                    O  /\\ / ___'_ __ _ _(_)_ __  __ _ \ \ \ \
[7/7/20 9:20:37:973 GMT] 0000004b SystemOut                                                    O ( ( )\___ | '_ | '_| | '_ \/ _` | \ \ \ \
[7/7/20 9:20:37:973 GMT] 0000004b SystemOut                                                    O  \\/  ___)| |_)| | | | | || (_| |  ) ) ) )
[7/7/20 9:20:37:973 GMT] 0000004b SystemOut                                                    O   '  |____| .__|_| |_|_| |_\__, | / / / /
[7/7/20 9:20:37:973 GMT] 0000004b SystemOut                                                    O  =========|_|==============|___/=/_/_/_/
[7/7/20 9:20:37:974 GMT] 0000004b SystemOut                                                    O  :: Spring Boot ::        (v2.3.0.RELEASE)
[7/7/20 9:20:38:131 GMT] 0000004b SystemOut                                                    O 2020-07-07 09:20:38.128  INFO 83952403 --- [RVICE_Thread-28] c.i.c.s.jcics.ServletInitializer         : Starting ServletInit
ializer on etp1.tsc.ibm.com with PID 83952403 (/var/cicsts/cicsts56/CT56B4A1/work/CT56B4A1/DFHWLP/wlp/usr/servers/defaultServer/installedApps/cics-java-liberty-springboot-jcics-0.1.0.war started by STCUSR in /ETP1/var/cic
sts/cicsts56/CT56B4A1/work)
[7/7/20 9:20:38:133 GMT] 0000004b SystemOut                                                    O 2020-07-07 09:20:38.133  INFO 83952403 --- [RVICE_Thread-28] c.i.c.s.jcics.ServletInitializer         : No active profile se
t, falling back to default profiles: default
[7/7/20 9:20:38:446 GMT] 00000053 com.ibm.ws.config.xml.internal.ConfigRefresher               A CWWKG0016I: Starting server configuration update.
[7/7/20 9:20:38:448 GMT] 00000053 com.ibm.ws.config.xml.internal.XMLConfigParser               A CWWKG0028A: Processing included configuration resource: /var/cicsts/cicsts56/CT56B4A1/work/CT56B4A1/DFHWLP/wlp/usr/servers/d
efaultServer/installedApps.xml
[7/7/20 9:20:38:450 GMT] 00000053 com.ibm.ws.config.xml.internal.ConfigRefresher               A CWWKG0018I: The server configuration was not updated. No functional changes were detected.
[7/7/20 9:20:39:214 GMT] 0000004b com.ibm.ws.webcontainer.webapp                               I SRVE0292I: Servlet Message - [cics-java-liberty-springboot-jcics-0.1.0]:.Initializing Spring embedded WebApplicationContext
[7/7/20 9:20:39:214 GMT] 0000004b SystemOut                                                    O 2020-07-07 09:20:39.214  INFO 83952403 --- [RVICE_Thread-28] o.s.web.context.ContextLoader            : Root WebApplicationC
ontext: initialization completed in 1011 ms
[7/7/20 9:20:39:608 GMT] 0000004b SystemOut                                                    O 2020-07-07 09:20:39.608  INFO 83952403 --- [RVICE_Thread-28] o.s.s.concurrent.ThreadPoolTaskExecutor  : Initializing Executo
rService 'applicationTaskExecutor'
[7/7/20 9:20:39:847 GMT] 0000004b SystemOut                                                    O 2020-07-07 09:20:39.846  INFO 83952403 --- [RVICE_Thread-28] c.i.c.s.jcics.ServletInitializer         : Started ServletIniti
alizer in 2.638 seconds (JVM running for 3347.897)[7/7/20 9:25:53:853 GMT] 00000045 com.ibm.ws.webcontainer.webapp                               I SRVE0292I: Servlet Message - [cics-java-liberty-springboot-jcics-0.1.0]:.Initializing Spring DispatcherServlet 'dispatcherSe
rvlet'
[7/7/20 9:25:53:853 GMT] 00000045 SystemOut                                                    O 2020-07-07 09:25:53.853  INFO 83952403 --- [HP.TASK205.CJSA] o.s.web.servlet.DispatcherServlet        : Initializing Servlet
 'dispatcherServlet'
[7/7/20 9:25:53:863 GMT] 00000045 SystemOut                                                    O 2020-07-07 09:25:53.863  INFO 83952403 --- [HP.TASK205.CJSA] o.s.web.servlet.DispatcherServlet        : Completed initializa
tion in 10 ms
[7/7/20 9:25:53:863 GMT] 00000045 com.ibm.ws.webcontainer.servlet                              I SRVE0242I: [cics-java-liberty-springboot-jcics-0.1.0] [/cics-java-liberty-springboot-jcics-ding] [dispatcherServlet]: Initia
lization successful.

アプリ稼働確認

先の例と同様、ブラウザからTSQに書き込むアプリを実行してみます。今度は書き込む文字列を”ILOVECICS2”にしています。 image.png 正常に結果が返りました。 CICS端末からCEBRで確認すると、きちんとデータが書き込まれていることが確認できました! image.png

サンプルのカスタマイズ

CICS TS V5.5 + APAR PH14856 or V5.6 base では、Spring Bootアプリを従来のCICSプログラムのように扱うことができるようになるため、EXEC CICS LINKでSpring Bootプログラムを呼び出したり、EXEC CICS STARTで呼び出すことができるようになります。 参考: Linking to a Java EE or Spring Boot application from a CICS program

ここでは、COBOLなどの言語からEXEC CICS LINK でSpring Bootアプリを呼び出すシナリオを試してみます。 EXEC CICS LINK でSpring Bootアプリを呼び出す際、データの受け渡しはChannel & Containerを使いますが、今回は簡素化のためデータ受け渡しは行わずに単純にプログラム呼び出しの部分のみ追加実装して試してみます。

server.xml変更

Liberty上のプログラムを呼び出す構成を行う場合、ランタイムとなるLibertyのフィーチャーとしてcicsts:link-1.0を追加する必要があります。以下のようにfeatureを追加してJVMServerを再起動(Disabled=>Enabled)しておきます。

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:link-1.0</feature>
    </featureManager>
...

サンプルプロジェクトをEclipseへ取り込む

上で取り扱ったGitHubで提供されているサンプルプロジェクトをEclipseに取り込みます。ここではCICS Explorerとして提供されているEclipseを使います。

Eclipse Marketplaceから、Buildship Gradle Integrationをインストールしておきます。 image.png image.png

Javaパースペクティブのパッケージ・エクスプローラー・ビューで、右クリック - インポート - フォルダまたはアーカイブからのプロジェクト で、cloneしたプロジェクトのディレクトリを選択して取り込みます。 image.png

取り込み後は赤×がついてエラー表示になっています。 image.png

プロジェクト右クリック - Gradle - Refresh Gradle Project image.png

エラーが消えました! image.png

ロジック追加

まず、build.gradleに依存関係を追加します。dependenciesに以下を追加します。

build.gradle


...
dependencies 
{
   ...
    // for @CICSProgram annotation
    compileOnly ("com.ibm.cics:com.ibm.cics.server.invocation.annotations")
    annotationProcessor ("com.ibm.cics:com.ibm.cics.server.invocation:5.6")
}

Refresh Gradle Projectを実行しておきます。

WriteTSQController.javaと同じパッケージに、以下のファイルを作成します。

WriteTSQLinked.java


package com.ibm.cicsdev.springboot.jcics;

import org.springframework.stereotype.Component;
import com.ibm.cics.server.CicsConditionException;
import com.ibm.cics.server.TSQ;
import com.ibm.cics.server.invocation.CICSProgram;

@Component
public class WriteTSQLinked {
 
    @CICSProgram("WRTTSQ")
    public void writeTSQlinked()
    {     
  String tsqName = "SPGJCICS";
  String record  = "ILOVECICS3";

  // Write to the TSQ
  try {
   // Construct the TSQ object
   TSQ tsqQ = new TSQ();
   tsqQ.setName(tsqName);

   // write the record to the TSQ
   tsqQ.writeString(record);  
   
  } catch ( CicsConditionException  e) {
   // Print the stack trace
   e.printStackTrace();
  }
    }
}

@CICSProgramアノテーションで、直後のメソッドを”WRTTSQ”という名前のCICSプログラムとして認識させています。 CICSプログラムとして認識させる場合、メソッドはpublic指定、引数なしで定義する必要があります。 今回は引数なしで、埋め込みでSPGJCICSというTSQにILOVECICS3という値を書き出すロジックを追加しています。

ビルド/デプロイ

C:\y\workspace\cicsts56\cics-springboot02>gradlew bootWar

BUILD SUCCESSFUL in 7s
2 actionable tasks: 2 executed
C:\y\workspace\cicsts56\cics-springboot02>gradlew deployCICSBundle> Task :cics-springboot-bundle04:buildCICSBundle
Adding Java-based bundle parts from'cicsBundlePart' dependency configuration
Adding Java-based bundle part:'C:\y\workspace\cicsts56\cics-springboot02\cics-java-liberty-springboot-jcics\build\libs\cics-java-liberty-springboot-jcics-0.1.0.war '
Adding non-Java-based bundle parts from'src/main/resources'

> Task :cics-springboot-bundle04:deployCICSBundle
Task deployCICSBundle

BUILD SUCCESSFUL in 1m 31s
4 actionable tasks: 3 executed, 1 up-to-date

When complete, the bundle will be installed and the WAR will be installed as a bundle part. Furthermore, the method specified by @CICSProgram contained therein is recognized as a CICS program, so the CICS program “WRTTSQ” is installed.

image.png

The details of the installed program definition are like this (check with CICS Explorer) image.png

A message like this appears in the JOBLOG of the target region.

DFHRL0107 I 07/08/2020 15:40:30 CT56B4A1 CICSUSER The CICS resource lifecycle manager has started to create the BUNDLE resource
           SPBBUNDL.
DFHRL0125 I 07/08/2020 15:40:30 CT56B4A1 CICSUSER BUNDLE resource SPBBUNDL is being created with BUNDLEID cics-springboot-bundle04
           and version 1.0.0.
DFHSJ1105 07/08/2020 15:40:30 CT56B4A1 WAR bundle cics-java-liberty-springboot-jcics-0.1.0 version 1.0.0 from BUNDLE SPBBUNDL has
           been installed as Disabled.
DFHRL0108 I 07/08/2020 15:40:30 CT56B4A1 CONL The CICS resource lifecycle manager is in the process of creating the BUNDLE resource
           SPBBUNDL and the BUNDLE is in the enabling state.
DFHRD0128 I 07/08/2020 15:40:30 CT56B4A1 CICSUSER CONL INSTALL BUNDLE(SPBBUNDL)
???? ??? CONL CICSUSER 07/08/20 15:40:30 INSTALL BUNDLE(SPBBUNDL) GROUP(TAGGRP)
DFHFC0961 07/08/2020 15:40:30 CT56B4A1 Calculation of LSR pool 1 parameters incomplete.Filename DFHDBFK has no DSNAME.
DFHPG0101 07/08/2020 15:40:34 CT56B4A1 CICSUSER CJSP Resource definition for WRTTSQ has been added.
DFHSJ1204 07/08/2020 15:40:34 CT56B4A1 A linkable service has been registered for program WRTTSQ in JVMSERVER DFHWLP with classname
           com.ibm.cicsdev.springboot.jcics.WriteTSQLinked, method writeTSQlinked.
DFHSJ1107 07/08/2020 15:40:34 CT56B4A1 WAR bundle with symbolic name cics-java-liberty-springboot-jcics-0.1.0 version 1.0.0 has bee
           Enabled.
DFHRL0132 I 07/08/2020 15:40:34 CT56B4A1 CJSL All defined resources for BUNDLE SPBBUNDL are now in the enabled state.
DFHAP1900 07/08/2020 15:40:40 CT56B4A1 NONE CICSUSER CONL SET BUNDLE(SPBBUNDL) ENABLESTATUS(ENABLED) RESP(NORMAL) RESP2(0).

Application operation check

Let’s simply issue `CECI LINK PROGRAM(WRTTSQ)’ from the CICS terminal. image.png

Check the contents of TSQ “SPGJ CICS” with CEBR. image.png

Expected message is written! Now you can see the flow of calling the Spring Boot app using EXEC CICS LINK!