Running CICS-Java application - (4) Spring Boot Application

This article is translated from the Japanese article below.
https://qiita.com/tomotagwork/items/9bdef46069e1591103ba
([google translate](https://translate.google.com/) was used.)

# 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 run on CICS (with Liberty on CICS). Running on CICS means that you can use JCICS, which uses CICS functions, so web apps that call existing CICS programs, web apps that access CICS-managed VSAMs and TSQs, etc., run only with CICS. It also means that you can develop it using the Spring Boot framework.

In this article, I will run a sample CICS-Spring Boot app provided on GitHub below.
[cics-java-liberty-springboot-jcics](https://github.com/cicsdev/cics-java-liberty-springboot-jcics)

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

## Related articles
[Running CICS-Java application - (1) Simple application](https://qiita.com/tomotagwork/items/b3c48da38925e7acd98c)
[Running CICS-Java application - (2) Build management with Maven](https://qiita.com/tomotagwork/items/16cbf233152cf64b42f4)
[Running CICS-Java application - (3) Build management with Gradle](https://qiita.com/tomotagwork/items/347283447a575c44c242)
[Running CICS-Java application - (4) Spring Boot Application](https://qiita.com/tomotagwork/items/bace965b77567146b7dc)
[Running CICS-Java application - (5) Using JCICSX](https://qiita.com/tomotagwork/items/7f93a23c7cca38287a11)


# Environment
**Development Environment**
Windows10
CICS Explorer V5.5.0.9

**Runtime Environment**
z/OS V2.4
CICS Transaction Server for z/OS V5.6

# Preparation
Note: If you use Gradle for build management, the target CICS must be under CICSplex management.

## Development Environment(PC)

### JavaEE Development Environment
Please use something that can develop Java EE applications such as Eclipse and VS Code as appropriate.
Since we will use the sample as it is this time, we will not edit the source in particular, so we do not have to use it, but usually we will use some kind of development environment. It would be nice to be able to work with Maven, git, etc.
If you use CICS Explorer together, you can use Eclipse.

### CICS Explorer
This is also not required, but it can be used to check the CICS resource definition.
Download and set up an Eclipse-based tool called CICS Explorer, referring to the following areas.
Reference: [Downloading and starting CICS Explorer](https://www.ibm.com/docs/en/cics-explorer/5.5.0?topic=downloading-starting-cics-explorer)
* This tool is free of charge for CICS users.

### Gradle

Follow the steps below to install.
[Installing Gradle](https://docs.gradle.org/6.5/userguide/installation.html)
Basically, just unzip the downloaded one and add 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 at the moment from the following(gradle-6.5.zip)。
[Releases](https://gradle.org/releases/)

Extract to a suitable directory. Here,`c:\x\Gradle\gradle-6.5\`.
Add bin directory (`C:\x\Gradle\gradle-6.5\bin`) to your PATH.

```
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

I will get and use the sample provided on gitHub, so I also have git installed.
I omit the setup instruction.

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

## Runtime Environment(z/OS, CICS)
*The z/OS side is exactly the same as the Maven case. If you have already implemented the Maven scenario, you can use the same one as it is.

Prepare a CICS region to run the sample.
For now, we'll use a region named **CT56B4A1** under the control of the CICSplex.
Add a resource called JVMServer to run Java applications.
This time, we will use the sample for CICS-Liberty (JavaEE application), so create a JVMServer for Liberty.

### 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 `/var/cicsts/cicsts56/CT56B4A1/JVMProfiles` and copy `/usr/lpp/cicsts/cicsts56/JVMProfiles/DFHWLP.jvmprofile`(sample definition for Liberty located under the CICS installation directory) to it. Customize as appropriate for your environment.

```xxx: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 properties file is located in the SIT parameter "JVMPROFILEDIR".

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

Restart the region for the changes to be enabled.

### JVMServer definition

Prepare the JVMSERVER resource definition.
Copy the JVMSERVER definition "DFHWLP" in the product-provided DFH$WLP group to an appropriate 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:21                                         
  CHANGETime     : 06/04/20 16:20:21                                         
  CHANGEUsrid    : CICSUSER                                                  
  CHANGEAGEnt    : CSDApi             CSDApi | CSDBatch                      
  CHANGEAGRel    : 0730                                                                     
```

Jvmprofile: DFHWLP, which 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 it is enabled by checking with `CEMT I JVMSERVER`.

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

### Modify server.xml
In this sample execution procedure, it is a procedure to deploy manually instead of automatically deploying, so add the setting for that.

If you specify `-Dcom.ibm.cics.jvmserver.wlp.autoconfigure=true` in the JVM profile, Liberty is configured automatically. Once the JVMSERVER definition is installed, Liberty is configured under the work directory (`work/CT56B4A1/DFHWLP/wlp/usr/servers/defaultServer`).
Modify server.xml under this directory so that it looks like this:

```xml:server.xml
...
<applicationMonitor dropins="dropins" dropinsEnabled="true" pollingRate="5s" updateTrigger="polled"/>
...
```

Thus, specify `dropsEnabled="true"`, `updateTrigger="polled"`.
This will automatically detect the war placed in the drops directory.
Create a drops directory in the same directory (`.../work/CT56B4A1/DFHWLP/wlp/usr/servers/defaultServer/drops`).

After making changes, restart the JVM Server.

### CICS Bundle Deployment API
You must have the CICS Bundle Deployment API set up, which is available from 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 CMCI JVM server properties.
Reference: [How it works: CICS bundle deployment API](https://www.ibm.com/docs/en/cics-ts/5.6?topic=cmci-how-it-works-cics-bundle-deployment-api)

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

# Running the sample application(1) / Manual deployment

First, I will try to run according to the procedure provided on github。
Reference: [cics-java-liberty-springboot-jcics](https://github.com/cicsdev/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 file structure
Go to the directory "cics-java-liberty-springboot-jcics" and take a look at the structure of the file.

```
c:\y\workspace\cicsts56\cics-java-liberty-springboot-jcics>tree /f /a
フォルダー パスの一覧:  ボリューム Windows
ボリューム シリアル番号は 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.Does not include the CICS Bundle project.
It seems that it supports both Maven and Gradle, so here I will use Gradle.

## Check/Edit contents
There are several sources. Let's take a look at WriteTSQController.java, for example. Just check, not modify.

```java: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;
	}
}
```

It is a simple application that just writes data to TSQ using the TSQ class of JCICS. The query parameter of URI `/ writeTSQs` receives tsqName and tsqContent, and writes the value specified by tsqContent to the TSQ specified by tsqName.

Check context-root in ibm-web-ext.xml. This is also confirmation only.

```xml: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>
```

Open build.gradle and edit the dependency specifications to match your target CICS version. Since we are targeting CICS TS V5.6 here, modify it as follows.

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

The value to be specified will be judged from the following.
Reference:[IBM CICS TS BOM](https://mvnrepository.com/artifact/com.ibm.cics/com.ibm.cics.ts.bom)

## Build

Build with the following command.

```
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
```

If successful, the following WAR will be created.
`build/libs/cics-java-liberty-springboot-jcics-0.1.0.war`

## Deploy
In the procedure of this sample, WAR is deployed manually, so let's try it once.

Transfer the above WAR file in binary mode to the drops directory you created earlier.
The app should now be recognized automatically. (For this method, the BUNDLE definition is not used)

## Running the sample application
From the browser, try making the following request to the host:port that the target Liberty is listening to.
`http://etp1:56441/cics-java-liberty-springboot-jcics-ding/writeTSQs?tsqName=SPGJCICS&tsqContent=ILOVECICS`
You will put the message ILOVECICS in a TSQ named SPGJCICS.
Hopefully, the data will be written to TSQ, so check it with CEBR from the CICS terminal.
![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/132331/2a036830-9eeb-a2c4-6320-4d6a9776c959.png)
I was able to confirm that the data was properly input.

# Running the sample application(2) / Deploy by Gradle

By the way, if the above procedure is done, the deployment will be manual and it is not smart, so let's add a CICS Bundle project so that Deploy can be issued with Gradle.

<font color="red"> Notice: If you tried manual deployment with the above steps, the app will batting, so remove the war in the drops directory and restart JVMSERVER.</font>

## Create Gradle multi project
Add a CICS Bundle project and create a parent project to combine with the WAR provided in the sample.

### Parent project
First, create a directory `cics-springboot01` as a parent project directory and run the gradle wrapper on it.

```
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
フォルダー パスの一覧:  ボリューム Windows
ボリューム シリアル番号は 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.

```gradle:build.gradle
group 'com.ibm.cicsdev.springboot'
version '1.0.0'
```

```gradle:setting.gradle
rootProject.name = 'cics-springboot01'
include 'cics-java-liberty-springboot-jcics'
include 'cics-springboot-bundle04'
```

### Child project(1) / for WAR
I use the project provided in the sample as it is.
Clone cics-java-liberty-springboot-jcics with git clone under the parent project directory as shown above.
Then modify the "compileOnly" line in build.gradle to match your target CICS version.


### Child project(2) / for CICS Bundle
Create build.gradle for the bundle, referring to the previous article.
Reference: [Running CICS-Java application - (3) Build management with Gradle]()

Under the parent project directory, create a directory named `cics-springboot-bundle04` and create a build.gradle like the one below. Match the directory name to the name specified in the parent setting.gradle.

```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) The CICSplex name to which the target CICS region belongs
        region   = 'CT56B4A1'       // (3) Target CICS region name
        bunddef  = 'SPBBUNDL'       // (4) Bundle resource name defined on the target CICS region
        csdgroup = 'TAGGRP'         // (5) CSD group name to which the bundle definition in (4) belongs
        url      = 'http://etp1:56002'     // (6) CMCI URL for WUI
        username = 'TAG'           // (7) User and password used when issuing Deployment API by CMCI
        password = 'xxxxxxxx'      // 
        //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 will look like this.

```
c:\y\workspace\cicsts56\cics-springboot01>tree /a /f
フォルダー パスの一覧:  ボリューム Windows
ボリューム シリアル番号は 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
```

## Create BUNDLE definition
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 the CSD group based on (5), the BUNDLE definition name (4), and the BUNDLEDIR based on the directory name and version information value of the project.
*Here, the installation operation is not performed yet.

## Build/Deploy

Build the 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](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/132331/9321b30e-acfa-0907-aa2e-bb1d5e3473f4.png)
I was able to deploy with Gradle!

By the way, if you look at Liberty's messages.log, you can see that the Spring Boot app is running.

```
[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.
```

## Running the sample application

As in the previous example, let's run the app that writes to TSQ from the browser. This time, the character string to be written is set to "I LOVECICS2".
![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/132331/ef085e86-264b-12de-627c-14fe2b70e785.png)
The result was returned normally.
When I checked with CEBR from the CICS terminal, I was able to confirm that the data was written properly!
![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/132331/caef1c54-38b4-0c23-305c-2d81f276f780.png)


# Customize the sample application

With CICS TS V5.5 + APAR PH14856 or V5.6 base, you can treat your Spring Boot app like a traditional CICS program, so you can call the Spring Boot program with EXEC CICS LINK or with EXEC CICS START.
Reference: [Linking to a Java EE or Spring Boot application from a CICS program](https://www.ibm.com/docs/en/cics-ts/5.6?topic=djariljs-linking-java-ee-spring-boot-application-from-cics-program)

Here, we will try a scenario that calls a Spring Boot app with EXEC CICS LINK from a CICS-COBOL program.
When calling the Spring Boot application with EXEC CICS LINK, data is passed using Channel & Container, but for the sake of simplicity, we will simply add and implement only the program call part without passing data.

## Modify server.xml

When configuring to call a program on Liberty, it is necessary to add `cicsts:link-1.0` as a feature of Liberty which is the runtime. Add the feature as shown below and restart the JVM Server (Disabled => Enabled).

```xml: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>
...
```

## Import sample project into Eclipse

Import the sample project provided on GitHub mentioned above into Eclipse. Here, we use Eclipse provided as CICS Explorer.

Install Buildship Gradle Integration from the Eclipse Marketplace.
![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/132331/ca04600b-3d5e-acef-24ed-231f65dc8b28.png)
![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/132331/ae9af268-bb88-ac43-d00f-2f71767064c7.png)

In the Java Perspective's Package Explorer view, right-click - "Import" - "Project from Folder or Archive", select the cloned project directory to import.
![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/1424383/94cfc1eb-dee1-3ad3-43f5-cf0c37ed0683.png)

After importing, a red x is attached and an error is displayed.
![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/132331/2ac8d8ee-1a97-3608-f504-f111141fd1d9.png)

Right click on the project - Gradle - Refresh Gradle Project
![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/132331/07d6315d-90f0-6330-a602-1ed2fbbf96bd.png)

The error has disappeared!
![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/132331/aad554c7-84ea-f33a-8c33-e85078d393f1.png)

## Add logic

First, add a dependency to build.gradle. 
Add the following to dependencies.

```gradle: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")
}
```

Run the Refresh Gradle Project.

Create the following files in the same package as WriteTSQController.java.

```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();
		}
    }
}
```

The `@CICSProgram` annotation makes the method immediately after it recognized as a CICS program named "WRTTSQ".
To recognize it as a CICS program, the method must be defined with a public specification and no arguments.
This time, I added the logic to write the value ILOVECICS3 to TSQ "SPGJCICS" with hard-coding.

## Build/Deploy

```
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` included in it is recognized as a CICS program, so the CICS program" WRTTSQ "is installed.
![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/132331/e692eef0-9ea1-ad67-2faa-1a4a6c3ae66d.png)

The details of the installed program definition are like this (check with CICS Explorer)
![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/132331/1d4af0e1-8637-8488-aad8-83de72fed599.png)

Messages like this appears in the JOBLOG in 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).        
```

## Running the customized application

I will simply issue `CECI LINK PROGRAM (WRTTSQ)` from the CICS terminal.
![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/132331/5f60c6bd-a3b7-967b-2c19-e3bf31b5b8b1.png)

Let's check the contents of TSQ "SPGJCICS" with CEBR.
![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/132331/594bddcb-a275-f646-c789-6d9a0638e9f7.png)

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