CICS-Javaアプリケーションを動かす - (1)単純なサンプルアプリの稼働

# はじめに
CICS Transaction Server for z/OS のアプリケーション開発言語と言えば、COBOL, PL/I, Asembler辺りが使われることが多いですが、ずいぶん前からJavaもサポートされています。つまり、CICSのアプリケーションをJavaで書けるということです。EXEC CICSコマンドに相当するJavaのクラスライブラリ(JCICS)が提供されるので、Javaのメソッドを使ってEXEC CICS LINKとかEXEC CICS STARTみたいな操作を行うことができます。
ここではCICS-Javaアプリのサンプル(OSGi準拠)を実際に動かすところをやってみます。

※ちなみにCICS上でJavaEEアプリを動かすということもできます。
参考: [CICS上でJavaEEアプリケーションを動かす](https://qiita.com/tomotagwork/items/03528b37077574f33ad9)

## 関連記事
[CICS-Javaアプリケーションを動かす - (1)単純なサンプルアプリの稼働](https://qiita.com/tomotagwork/items/aac10ad84fe83d88bb5f)
[CICS-Javaアプリケーションを動かす - (2)Mavenによるビルド管理](https://qiita.com/tomotagwork/items/a487484835d4e8dd2d6f)
[CICS-Javaアプリケーションを動かす - (3)Gradleによるビルド管理](https://qiita.com/tomotagwork/items/6fae5bd3440635ad26af)
[CICS-Javaアプリケーションを動かす - (4)Spring Bootアプリ](https://qiita.com/tomotagwork/items/9bdef46069e1591103ba)
[CICS-Javaアプリケーションを動かす - (5)JCICSXの利用](https://qiita.com/tomotagwork/items/cac290f6435453c19b7b)



# 環境情報
**開発環境**
Windows10
CICS Explorer V5.6(Beta)

**実行環境**
z/OS V2.4
CICS Transaction Server for z/OS V5.6(Beta)

# CICSのJavaサポートについて
CICSのJavaサポートについて整理しておきます。
CICSではOSGi準拠のJavaアプリケーションがサポートされます。
Javaで実装したCICSアプリを動す場合、以下のような手続きが必要になります。

**ランタイム準備**
Javaアプリケーションを実行するために、ターゲットのCICSリージョンにJVMSERVERという資源定義を作成しJavaの実行環境を用意しておきます。

**開発**
開発作業はEclipseベースの無償ツール"CICS Explorer"で行います。
JCICSのライブラリーをimportしたJavaアプリを作成し、OSGiバンドル(jarの拡張のようなもの)という形でパッケージングします。(参考:[OSGI概要](https://qiita.com/tomotagwork/items/6329ca77477f6ccda078) )　この時、CICSプログラムとして認識させたい先頭のロジックはmain関数で実装する必要があります。
いくつかのOSGi Bundleを"CICSバンドル"という単位にパッケージングします。
※CICS上ではLibertyも稼働させることができ、JavaEEアプリをCICS上のLibertyで稼働させることもできます。その場合JavaEEアプリはWARやEARの単位でパッケージされますが、その場合もそれらを"CICSバンドル"という単位にパッケージングするという考え方は同様です。

**デプロイ**
CICSバンドルを実行環境のz/OSのUSS上に転送します。
CICSリージョンの資源定義でBUNDLE定義を作成し、USS上に転送したCICSバンドル(Javaアプリ)を認識させます。
CICSリージョンの資源定義でPROGRAM定義を作成し、BUNDLEに含まれるJavaクラスをCICSプログラムとして登録します。

各CICS資源定義と実体との関連は以下の通りです。
![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/132331/e734e2fe-de25-f776-ec6d-02b474775284.png)


# 事前準備

## 開発環境
以下の辺りを参考にCICS ExplorerというEclipseベースのツールをダウンロードしてセットアップしておきます。
参考:[Downloading and starting CICS Explorer](https://www.ibm.com/support/knowledgecenter/SSSQ3W_5.5.0/com.ibm.cics.core.help/topics/concepts/install_planning_client.html)
※このツールはCICS利用者は無償で使えるツールです。

ホスト接続定義として、ターゲットとなるCICSが稼働するz/OSに対してFTP接続構成をしておきます。
![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/132331/73430f85-97d2-fa86-0189-8f7dbd576f01.png)


## 実行環境
サンプルを稼働させるCICSリージョンを用意します。
ここでは、**CT56B4A1**という名前のリージョンを使うことにします。
そこに、Javaアプリケーションを稼働させるためのJVMServerという資源を追加します。

### JVMプロファイル

USS上にJVMプロファイルを準備します。(JVMServerに関するプロパティーは実質このUSS上のファイルに指定します。JVMSERVER資源定義ではこのJVMプロファイルのファイル名をポイントすることになります。)
サンプルが提供されているのでそれをコピーして使用します。

/var/cicsts/cicsts56/CT56B4A1/JVMProfiles というディレクトリを作成し、そこに/usr/lpp/cicsts/cicsts56/JVMProfiles/DFHOSGI.jvmprofile(CICS導入ディレクトリ下に配置されているOSGi用のサンプル定義)をコピーします。
環境に合わせて適宜カスタマイズします。

```xxx:DFHOSGI.jvmprofile抜粋
JAVA_HOME=/usr/lpp/java/J8.0_64/
WORK_DIR=/var/cicsts/cicsts56/CT56B4A1/work
-Xms32M
-Xmx256M
-Xmso1M
-Xgcpolicy:gencon
-Xscmx256M
-Xshareclasses:name=cicsts%g,groupAccess,nonfatal
-Xtune:virtualized
-Dcom.ibm.tools.attach.enable=no
_BPXK_DISABLE_SHLIB=YES
```

### SIT

上のプロパティーファイルを配置したディレクトリを、SITパラメーター"JVMPROFILEDIR"に指定します。

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

変更反映のためにリージョンを再起動します。

### JVMServer定義

JVMSERVER資源定義を準備します。
製品提供のDFH$OSGIというグループにあるJVMSERVER定義"DFHJVMS"を適当なグループにコピーしてインストールします。

```
OBJECT CHARACTERISTICS                                    CICS RELEASE = 0730 
 CEDA  View JVmserver( DFHJVMS  )                                             
  JVmserver      : DFHJVMS                                                    
  Group          : TAG$OSGI                                                   
  DEScription    : CICS JVM server to run OSGi samples                        
  Status         : Enabled            Enabled | Disabled                      
  Jvmprofile     : DFHOSGI                                        (Mixed Case)
  Lerunopts      : DFHAXRO                                                    
  Threadlimit    : 015                1-256                                   
 DEFINITION SIGNATURE                                                         
  DEFinetime     : 06/02/20 17:28:17                                          
  CHANGETime     : 06/02/20 17:28:17                                          
  CHANGEUsrid    : CICSUSER                                                   
  CHANGEAGEnt    : CSDApi             CSDApi | CSDBatch                       
  CHANGEAGRel    : 0730                                                       
```

※Jvmprofile: DFHOSGIとなっていますが、これはSITのJVMPROFILEDIRに指定されたディレクトリ下のDFHOSGI.jvmprofileというファイルがJVMプロパティーファイルとして使用されることを意味します。



CEMT I JVMSERVERで見てEnableになっていればOK。

```
I JVMS                                               
STATUS:  RESULTS - OVERTYPE TO MODIFY                
 Jvm(DFHJVMS ) Ena     Prf(DFHOSGI ) Ler(DFHAXRO )   
    Threadc(000) Threadl( 015 ) Cur(9965280)         

```

### bundleファイル配置用ディレクトリ
bundleファイルを配置するディレクトリをUSS上に作成しておきます。
ここでは、`/var/cicsts/cicsts56/CT56B4A1/bundles/`というディレクトリを作成しておくことにします。

# サンプルアプリ稼働確認
参考: [Java samples: JCICS examples](https://www.ibm.com/support/knowledgecenter/SSGMCP_5.6.0/reference-samples/java_samples_jcics.html)

## サンプルプロジェクトの作成

CICS Explorerのメニューからウィンドウ-設定を選択して設定ウィンドウを開きます。
プラグイン開発-ターゲット・プラットフォームを選択し、追加をクリックします。
![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/132331/247ec677-815e-cfdb-a205-42e7af1459ea.png)

テンプレートで対象のCICSのバージョンを選択します。ここではCICS TS V5.6を選択。
![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/132331/469cb800-28d1-2562-bfe2-abfe7e9096a9.png)

追加されたCICS TS 5.6をチェックして適用します。
![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/132331/045402a8-2e8f-584b-ca58-d3382a00a24e.png)

Javaパースペクティブで、メニューからファイル-新規-その他を選択
![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/132331/134c2a61-7d30-bd24-f3a1-7144c5046585.png)

CICSバンドルOSGiサンプルを選択
![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/132331/166d1a1f-ac87-3e86-27d9-671adbd5fc7c.png)

そのまま次へ
![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/132331/dfdea7ad-37ce-e436-20d3-c35dac142d7b.png)

そのまま終了
![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/132331/b72a1ba8-57fe-3523-680f-3563356ed751.png)

サンプル・プロジェクトが作成されます。
![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/132331/a86b44eb-f9a6-1327-c60e-1a6990b8c437.png)

## サンプルの中身確認
このプロジェクトではいくつかのサンプルアプリが提供されていますが、そのうちの一番シンプルなHello Worldのソースを見てみます。
(com.ibm.cics.server.examples.helloプロジェクト(OSGiバンドル)に含まれるexamples.hello.HelloCICSWorld.java)

```java:HelloCICSWorld.java
package examples.hello;

import com.ibm.cics.server.CommAreaHolder;
import com.ibm.cics.server.Task;

public class HelloCICSWorld
{
    public static void main(CommAreaHolder CAH)
    {
        Task t = Task.getTask();
        if ( t == null )
            System.err.println("HelloCICSWorld example: Can't get Task");
        else
            t.out.println("Hello from a Java CICS application");
    }
}
```

JCICSのcom.ibm.cics.server.Taskが使われています。
Task.outは端末出力のためのPrintWriterを意味するので、端末に対して単純な文字列を送信するロジックになっています。
参考: [Javadoc - Task](https://www.ibm.com/support/knowledgecenter/SSGMCP_5.6.0/reference-javadocs/jcics-javadoc/com/ibm/cics/server/Task.html?view=embed#out)

同プロジェクトのMETA-INF/MANIFEST.MFを確認してみます。

```
Manifest-Version: 1.0
Bundle-ManifestVersion: 2
Bundle-Name: Hello Plug-in
Bundle-SymbolicName: com.ibm.cics.server.examples.hello
Bundle-Version: 1.0.0
Bundle-RequiredExecutionEnvironment: J2SE-1.4,
 J2SE-1.5,
 JavaSE-1.6
Import-Package: com.ibm.cics.server;version="[1.0.0,2.0.0)"
CICS-MainClass: examples.hello.HelloCICSWorld, examples.hello.HelloWorld
```

CICS-MainClassの指定で、mainメソッドを持つクラスを指定しています。ここで指定されたクラスのmainメソッドがCICSプログラムとして認識可能です(プログラム定義と紐づけ可能)。

com.ibm.cics.server.examples.bundleというCICSバンドルプロジェクトを確認します。
META-INF/cics.xmlをCICSバンドルマニフェストエディターで開くと、上のOSGiバンドルが含まれていることが確認できます。
![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/132331/e242e601-9579-0c38-3b9b-b5547bb6494a.png)

com.ibm.cics.server.examples.hello.osgibundleを開きます。
![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/132331/4fc8a7e8-52d1-dfac-810e-36e61d003b02.png)

ここに指定されているjvmserverの値を確認します。ここには稼働させるJVMSERVER定義の名前を指定する必要があります。事前準備の所で作成したJVMSERVER定義の名前に合わせて修正します。サンプル定義を同名でコピーしている場合はDFHJVMSになっていると思うので変更は不要です。


## アプリケーションをCICSへデプロイ
CICSへのデプロイは、"CICSバンドル"の単位で行います。
com.ibm.cics.server.examples.bundleプロジェクトを右クリックしてz/OS UNIXファイルシステムへのバンドル・プロジェクトのエクスポートをクリック
![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/132331/01af1069-c161-04de-9438-34d493bc01d4.png)

ファイルシステム内の特定のロケーションにエクスポートを選択して次へ
![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/132331/cc80a3b3-c52d-6a8c-3923-71d53ee0d724.png)

先に作成しておいたbundleファイル配置用のディレクトリを指定して終了
![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/132331/ed945398-3da7-3798-3b2b-f53eff1506a6.png)

メッセージを確認
![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/132331/625bae36-89b3-a85a-3bb8-66505ea6f0db.png)
バンドルファイルがUSS上に配置されました。

CICS提供のDFH$OSGIグループの各リソースを適当なグループにコピーします。
BUNDLE定義"DFH$OSGB"をカスタマイズして、BUNDLEDIRの値を、上でバンドルファイルを配置したディレクトリ(`/var/cicsts/cicsts56/CT56B4A1/bundles/com.ibm.cics.server.examples.bundle_1.0.0`)に置き換えます。

```
OVERTYPE TO MODIFY                                        CICS RELEASE = 0730
 CEDA  ALter Bundle( DFH$OSGB )                                              
  Bundle         : DFH$OSGB                                                  
  Group          : TAG$OSGI                                                  
  DEScription  ==> CICS bundle containing OSGi sample bundles                
  Status       ==> Enabled            Enabled | Disabled                     
  BUndledir    ==> /var/cicsts/cicsts56/CT56B4A1/bundles/com.ibm.cics.server.
  (Mixed Case) ==> examples.bundle_1.0.0                                     
               ==>                                                           
               ==>                                                           
               ==>                                                           
  BAsescope    ==>                                                           
  (Mixed Case) ==>                                                           
               ==>                                                           
               ==>                                                           
               ==>                                                           
 DEFINITION SIGNATURE                                                        
  DEFinetime     : 06/02/20 18:27:37                                         
  CHANGETime     : 06/02/20 18:27:37                                         
```

インストールしてEnableになることを確認します。

```
I BUNDLE                                                 
STATUS:  RESULTS - OVERTYPE TO MODIFY                    
 Bun(DFH$OSGB) Ena         Par(00003) Tar(00003)         
    Enabledc(00003) Bundlei(com.ibm.cics.server.exampl)  
```

ちなみにCICS Explorerで資源定義確認すると、BUNDLE定義だけでなくBUNDLEに含まれるBUNDLEPARTSも確認できます。
![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/132331/25d8c3ad-de5d-16cf-fd0b-e3445f708683.png)

## サンプル実行

今回はHello Worldのサンプルを実行してみるので、このサンプルに関連する資源定義を追加でインストールします。
参考: [Running the Hello World example](https://www.ibm.com/support/knowledgecenter/SSGMCP_5.6.0/reference-samples/dfhpjmy.html)

プログラム定義"DFJ$JHE2"と、トランザクション定義"JHE2"ですね。実体であるJavaプログラムはBUNDLEとして先にインストール済みです。
いずれもDFH$OSGIに提供されているのでコピーしてそのままインストールします。
ちなみにDFH$JHE2の定義を覗いてみると、

```
OBJECT CHARACTERISTICS                                    CICS RELEASE = 0730 
 CEDA  View PROGram( DFJ$JHE2 )                                               
  PROGram        : DFJ$JHE2                                                   
  Group          : TAG$OSGI                                                   
  DEScription    : OSGi Hello CICS world sample program                       
  Language       :                    CObol | Assembler | Le370 | C | Pli     
  RELoad         : No                 No | Yes                                
  RESident       : No                 No | Yes                                
  USAge          : Normal             Normal | Transient                      
  USElpacopy     : No                 No | Yes                                
  Status         : Enabled            Enabled | Disabled                      
  RSl            : 00                 0-24 | Public                           
  CEdf           : Yes                Yes | No                                
  DAtalocation   : Any                Below | Any                             
  EXECKey        : Cics               User | Cics                             
  COncurrency    : Required           Quasirent | Threadsafe | Required       
  Api            : Cicsapi            Cicsapi | Openapi                       
 REMOTE ATTRIBUTES                                                            
  DYnamic        : No                 No | Yes                                
  REMOTESystem   :                                                            
  REMOTEName     :                                                            
  Transid        :                                                            
  EXECUtionset   : Fullapi            Fullapi | Dplsubset                     
 JVM ATTRIBUTES                                                               
  JVM            : Yes                No | Yes                                
  JVMClass       : examples.hello.HelloCICSWorld                              
  (Mixed Case)   :                                                            
                 :                                                            
                 :                                                            
                 :                                                            
  JVMServer      : DFHJVMS                                                    
  JVMProfile     :                                                (Mixed Case)
 JAVA PROGRAM OBJECT ATTRIBUTES                                               
  Hotpool        : No                 No | Yes                                
...
```

こんな感じで、JVM:Yes, JVMClass:examples.hello.HelloCICSWorld, JVMServer:DFHJVMSが指定されています(BUNDLEPARTSでインストールされているクラス)。※事前準備で作成したJVMServer名が違う場合はそれに合わせて適宜修正してください。

これで一通り資源は整ったので実行してみます。
CICS端末からJHE2トランザクションを実行します。
![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/132331/ca78fec1-b59d-bbbb-331a-5a35b8bab843.png)
Hello from a Java CICS applicationというJavaプログラムから出力している文字列が表示されました！
これでJavaがCICSプログラムとして動いたことが確認できました。