This article is translated from the Japanese article below.
https://qiita.com/tomotagwork/items/9bdef46069e1591103ba
(google translate 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
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
Running CICS-Java application - (2) Build management with Maven
Running CICS-Java application - (3) Build management with Gradle
Running CICS-Java application - (4) Spring Boot Application
Running CICS-Java application - (5) Using JCICSX
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
- This tool is free of charge for CICS users.
Gradle
Follow the steps below to install.
Installing Gradle
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
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.
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:
...
<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
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
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.
/* 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 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.
...
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
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.
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.
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.
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.
group 'com.ibm.cicsdev.springboot'
version '1.0.0'
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.
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.
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".
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!
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
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).
...
<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.
In the Java Perspective's Package Explorer view, right-click - "Import" - "Project from Folder or Archive", select the cloned project directory to import.
After importing, a red x is attached and an error is displayed.
Right click on the project - Gradle - Refresh Gradle Project
The error has disappeared!
Add logic
First, add a dependency to build.gradle.
Add the following to dependencies.
...
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.
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.
The details of the installed program definition are like this (check with CICS Explorer)
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.
Let's check the contents of TSQ "SPGJCICS" with CEBR.
The expected message is written!
Now you can see the flow of calling the Spring Boot app using EXEC CICS LINK!