はじめに
先の記事でz/OS上でルール実行できる環境まで整いました。
ここでは、ルールの開発をしてzRESへのデプロイを行いそれをz/OS上のCOBOLアプリケーションから呼び出す、という一連の流れをチュートリアルをベースに見ていきます。
関連記事
IBM Operational Decision Manager メモ - (1) 概要、Linuxへのインストール
IBM Operational Decision Manager メモ - (2) ルール開発から実行までの流れ
IBM Operational Decision Manager メモ - (3) Decision Center利用の流れ
IBM Operational Decision Manager メモ - (4) Linux上での環境セットアップ
IBM Operational Decision Manager メモ - (5) z/OS上での環境セットアップ
IBM Operational Decision Manager メモ - (6) z/OS上でのルール呼び出し
IBM Operational Decision Manager メモ - (7) zODM環境補足
全体像
COBOLからODM管理のルールを呼び出す場合に、1つ肝となるのは入出力データ構造をどのように作るかという点です。このデータ構造はCOBOL側はCOPYBOOK、ODM側はXOM/BOM として実装する必要があります。これらを作成するアプローチとしては主に2つのパターンがあります。
(1) XOM/BOM をベースにCOPYBOOKを作成する
(2) COPYBOOKをベースにXOM/BOMを作成する
(1)は例えば既にODM上に抽出されたルールが稼働していてJavaアプリから利用しているものがあり、それをCOBOLからも利用したいというケースが該当すると思います。
(2)は既存のCOBOLアプリからルールを抽出する場合に、その抽出したルールとの入出力データ構造をまずCOPYBOOKで定義したいというケースが該当すると思います。
ここでは(1)のアプローチで試してみます。
チュートリアル実施
以下のチュートリアルを実施していきます。
Tutorial: Sharing a BOM between Java and COBOL applications
Task 1: Importing an existing rule project
しばらくはWindows上のRule Designer(eclipse)上での作業になります。
まずサンプルとして用意されているルール・プロジェクトをインポートします。
Sample Consoleを開いてRule Designer - Tutorials - Cobol - Sharing a BOM between Java and COBOL applications - start 以下のImport projectsをクリック
SharingZMiniloanというプロジェクトがインポートされます。
※ここでは既に出来合いのルールをそのまま使うことになります。ルール開発そのものについては別の記事もご参照ください。
Task 2: Configuring the BOM for COBOL copybook generation
既にルールが作成されていますので、そのルールで使用されるBOMも定義されています。ここではBOMをベースにしてルール呼び出しで使用するCOBOL COPYBOOKを生成していきます。
プロジェクトを右クリックしてPropertiesを選択
左側のメニューからCOBOL Management を選択し、Addをクリック
modelをクリックしてOK
このプロジェクトで定義されているBOMに関して、Javaの型をCOBOLにどのようにマッピングするかの候補が表示されます。
JavaのString型はCOBOLのPIC Xにマッピングされますがデフォルトで長さが20に設定されるようです。またJavaのList型はCOBOLのOCCURSにマッピングされますがこちらはデフォルトで10回に設定されるようです。このようなデフォルトのマッピング情報で不都合がある場合は、ここで変更が可能です。
ここではmessagesのPIC Xの長さを60に変更してFinishをクリックします。
前の画面に戻るので、Manageをクリックします。
Browseをクリック
生成されるCOPYBOOKの配置先を選択します。ここではSharingZMiniloan-execution以下のcopyを選択し、ファイル名にはHBRLDAT2.cpyを指定します。
前の画面に戻るのでOKをクリック
Add Top-Level Objectをクリック (ここで、生成されるCOPYBOOKに追加する構造体を選択ます)
Borrowerを選択してOK
同様に、Top-Level ObjectとしてLoanも追加します。
以下のようにBorrower, LoanがTop-Level Objectに追加されたら、Nextをクリック
生成されるCOPYBOOK のプレビュー画面が表示されるので、内容を確認してFinishをクリック
前の画面に戻るので、Apply and Close をクリック
COPYBOOKが生成されました。
Task 3: Creating a deployment configuration
zRESにデプロイするための設定を行っていきます。
Decision Service MapからCreate deployment configurationをクリックします。
フォルダと名前を選択してFinish
Deploymentのエディターが開くのでDecision Operatinos以下のInclude decision operationsのリンクをクリック
Decision OperationsタブでConfigured Decision Operations以下の「+」ボタンをクリック
decision operationとして SharingZMiniloanOperationを選択してFinish
デプロイ対象のDecision Operationが選択されました。
Task 4: Deploying the decision service
zRESにルールをデプロイしていきます。
Deploymentのエディター - Decision Operaiontsタブで、Ruleset Version Policy欄でIncrement minor version numbersが選択されていることを確認
OverviewタブでTarget Servers欄のDefine target serversのリンクをクリック
「+」ボタンをクリック
Create Rule Execution Server connectionを選択してNext
zRESへのアクセス情報を設定してTest Connectionをクリック
テスト接続が成功することを確認してFinish
Deploy先のzRES情報が登録されました。
Overviewタブに戻って、Proceed to RuleApp deploymentのリンクをクリック
対象のOperationとターゲットを確認してNext
zRESの認証情報確認してNext
内容確認してFinish
Deploy結果が表示されます。
念のためブラウザからRESコンソールに接続し、エクスプローラータブを確認してみます。
以下のように、SharingZMiniloanがリストされていればOKです。
Task 5: Building your COBOL application
ルールのデプロイと、COBOLからルール呼び出しに使用するCOPYBOOKの生成ができたので、それを元に呼び出し元COBOLソースを作って動かしていきます。
COBOLのソースはサンプルが提供されているのでそれをそのまま使います。
Windowsにサンプルインストールすると、<Inst_Dir>\ODM8110\studio\tutorials\cobol\bomstartresz\answer\SharingZMiniloan-exucution\cobol\HBRMTUT2.COBOLにルール呼び出しを行うCOBOLバッチのサンプルが提供されます。
参考: ルール呼び出しを行うCOBOLバッチのソース
*
* Licensed Materials - Property of IBM
* 5655-Y31
* Copyright IBM Corp. 2011, 2021. All Rights Reserved.
*
* U.S. Government Users Restricted Rights:
* Use, duplication or disclosure restricted by GSA ADP Schedule
* Contract with IBM Corp.
*
IDENTIFICATION DIVISION.
PROGRAM-ID. "HBRMTUT2".
ENVIRONMENT DIVISION.
DATA DIVISION.
WORKING-STORAGE SECTION.
COPY HBRLDAT2.
01 WS-REASON-CODES.
COPY HBRC.
COPY HBRWS.
01 WS-MESSAGE-IDX PIC 9(2).
01 WS-MAX-LEN PIC 9(18).
PROCEDURE DIVISION.
MAIN SECTION.
* Get connection to rule execution server
CALL 'HBRCONN' USING HBRA-CONN-AREA
IF HBRA-CONN-COMPLETION-CODE EQUAL TO HBR-CC-OK THEN
DISPLAY 'connect zRules successful'
ELSE
IF HBRA-CONN-COMPLETION-CODE EQUAL TO HBR-CC-WARNING THEN
DISPLAY "Warning while setting up zRules connection"
DISPLAY "CC code " HBRA-CONN-COMPLETION-CODE
DISPLAY "RC code " HBRA-CONN-REASON-CODE
DISPLAY "Message " HBRA-RESPONSE-MESSAGE
ELSE
DISPLAY "connect zRules failed"
DISPLAY "CC code " HBRA-CONN-COMPLETION-CODE
DISPLAY "RC code " HBRA-CONN-REASON-CODE
DISPLAY "Message " HBRA-RESPONSE-MESSAGE
PERFORM HANDLE-ERRORS
END-IF
END-IF
* Init ruleset parameter data
MOVE 'John' TO name
MOVE 300 TO creditScore
MOVE 100000 TO yearlyIncome
MOVE 70 TO age
MOVE 35000 TO amount
MOVE 10 TO yearlyInterestRate
MOVE 300 TO yearlyRepayment
MOVE '20131231' TO effectDate
MOVE 'T' TO approved
MOVE 0 TO messages-Num
* Move ruleset parameters to table HBRA-RA-PARMETERS
MOVE ZERO TO HBRA-CONN-RETURN-CODES
MOVE LOW-VALUES TO HBRA-RA-PARMETERS
MOVE "/SharingZMiniloanApp/SharingZMiniloan"
TO HBRA-CONN-RULEAPP-PATH
* Parameter Borrower
MOVE LOW-VALUES TO HBRA-RA-PARMETERS.
MOVE 'borrower' TO HBRA-RA-PARAMETER-NAME(1)
MOVE LENGTH OF Borrower TO HBRA-RA-DATA-LENGTH(1)
SET HBRA-RA-DATA-ADDRESS(1)
TO ADDRESS OF Borrower
* Parameter Loan
MOVE 'loan' TO HBRA-RA-PARAMETER-NAME(2)
MOVE LENGTH OF Loan TO HBRA-RA-DATA-LENGTH(2)
SET HBRA-RA-DATA-ADDRESS(2)
TO ADDRESS OF Loan
* Invoke rule execution server
CALL 'HBRRULE' USING HBRA-CONN-AREA
* If there has been a failiure then display this, but continue
* because we will need to disconnect.
IF HBRA-CONN-COMPLETION-CODE IS GREATER THAN
HBR-CC-WARNING THEN
DISPLAY "invoke zRules failed"
DISPLAY "CC code " HBRA-CONN-COMPLETION-CODE
DISPLAY "RC code " HBRA-CONN-REASON-CODE
DISPLAY "Message " HBRA-RESPONSE-MESSAGE
ELSE
IF HBRA-CONN-COMPLETION-CODE EQUAL TO HBR-CC-OK THEN
DISPLAY 'invoke zRules successful'
ELSE
DISPLAY "Warning on invoking zRules"
DISPLAY "CC code " HBRA-CONN-COMPLETION-CODE
DISPLAY "RC code " HBRA-CONN-REASON-CODE
DISPLAY "Message " HBRA-RESPONSE-MESSAGE
END-IF
* Display result
DISPLAY "********** EXECUTION RESULT *********"
DISPLAY "Borrower Name : " name
DISPLAY "Loan Approved?: " approved
IF approved = "F"
DISPLAY "Reject messages:"
PERFORM VARYING WS-MESSAGE-IDX FROM 1 BY 1
UNTIL WS-MESSAGE-IDX > messages-Num
DISPLAY messages (WS-MESSAGE-IDX)
END-PERFORM
END-IF
DISPLAY "**************************************"
END-IF
* Get disconnect to rule execution server
CALL 'HBRDISC' USING HBRA-CONN-AREA
IF HBRA-CONN-COMPLETION-CODE EQUAL TO HBR-CC-OK THEN
DISPLAY 'Disconnected zRules successful'
ELSE
IF HBRA-CONN-COMPLETION-CODE EQUAL TO HBR-CC-WARNING THEN
DISPLAY "Warning while disconnecting from zRules"
DISPLAY "CC code " HBRA-CONN-COMPLETION-CODE
DISPLAY "RC code " HBRA-CONN-REASON-CODE
DISPLAY "Message " HBRA-RESPONSE-MESSAGE
ELSE
DISPLAY "Disconnect zRules failed"
DISPLAY "CC code " HBRA-CONN-COMPLETION-CODE
DISPLAY "RC code " HBRA-CONN-REASON-CODE
DISPLAY "Message " HBRA-RESPONSE-MESSAGE
PERFORM HANDLE-ERRORS
END-IF
END-IF.
MAIN-END.
STOP RUN.
HANDLE-ERRORS SECTION.
DISPLAY "Errors occurred. Unable to continue."
STOP RUN.
HANDLE-ERRORS-END.
EXIT.
参考: ソース解説
簡単にソースの解説をしておきます。
呼び出したいルールのBOMから生成したCOPYBOOK(HBRLDATA2)、および、ODMが提供する各種制御用変数が定義されたCOPYBOOK(HBRC, HBRWS)を取り込みます。
...
WORKING-STORAGE SECTION.
COPY HBRLDAT2.
01 WS-REASON-CODES.
COPY HBRC.
COPY HBRWS.
...
zRESとの接続を確立します。
...
* Get connection to rule execution server
CALL 'HBRCONN' USING HBRA-CONN-AREA
...
ルール呼び出しの際に受け渡したい値の設定をします。
...
* Init ruleset parameter data
MOVE 'John' TO name
MOVE 300 TO creditScore
MOVE 100000 TO yearlyIncome
MOVE 70 TO age
MOVE 35000 TO amount
MOVE 10 TO yearlyInterestRate
MOVE 300 TO yearlyRepayment
MOVE '20131231' TO effectDate
MOVE 'T' TO approved
MOVE 0 TO messages-Num
...
呼び出すルールセットのパスなどを設定します。
...
* Move ruleset parameters to table HBRA-RA-PARMETERS
MOVE ZERO TO HBRA-CONN-RETURN-CODES
MOVE LOW-VALUES TO HBRA-RA-PARMETERS
MOVE "/SharingZMiniloanApp/SharingZMiniloan"
TO HBRA-CONN-RULEAPP-PATH
...
先に値をセットした構造体をルールセット・パラメーターとしてセットします。
...
* Parameter Borrower
MOVE LOW-VALUES TO HBRA-RA-PARMETERS.
MOVE 'borrower' TO HBRA-RA-PARAMETER-NAME(1)
MOVE LENGTH OF Borrower TO HBRA-RA-DATA-LENGTH(1)
SET HBRA-RA-DATA-ADDRESS(1)
TO ADDRESS OF Borrower
* Parameter Loan
MOVE 'loan' TO HBRA-RA-PARAMETER-NAME(2)
MOVE LENGTH OF Loan TO HBRA-RA-DATA-LENGTH(2)
SET HBRA-RA-DATA-ADDRESS(2)
TO ADDRESS OF Loan
...
実際のルール呼び出しを行います。
...
* Invoke rule execution server
CALL 'HBRRULE' USING HBRA-CONN-AREA
...
結果を出力します。
...
* Display result
DISPLAY "********** EXECUTION RESULT *********"
DISPLAY "Borrower Name : " name
DISPLAY "Loan Approved?: " approved
IF approved = "F"
DISPLAY "Reject messages:"
PERFORM VARYING WS-MESSAGE-IDX FROM 1 BY 1
UNTIL WS-MESSAGE-IDX > messages-Num
DISPLAY messages (WS-MESSAGE-IDX)
END-PERFORM
END-IF
DISPLAY "**************************************"
...
zRESから切断します。
...
* Get disconnect to rule execution server
CALL 'HBRDISC' USING HBRA-CONN-AREA
...
Task 6: Executing the COBOL application
上のCOBOLバッチを動かしてみます。
Task 6: Executing the COBOL application
ここの手順だと、実行モジュールとして提供されているCOBOLバッチを動かすようになっていますが、せっかくなのでソースをコンパイルするところからやりたいと思います。
コンパイル/リンク/実行をするJCLのサンプルが、Windowsのサンプルをインストールしたディレクトリ下に提供されています。
<Inst_Dir>\ODM8110\studio\tutorials\cobol\bomstartresz\answer\SharingZMiniloan-exucution\jcl\HBRMTUT2.jcl
参考: サンプルJCL
//HBRMTUT2 JOB MSGCLASS=H,MSGLEVEL=(1,1),REGION=0M
// JCLLIB ORDER=(++LNGPRFX++.SIGYPROC)
//*********************************************************************
//* Licensed Materials - Property of IBM *
//* 5655-Y31 *
//* Copyright IBM Corp. 2011, 2021. All Rights Reserved. *
//* U.S. Government Users Restricted Rights: *
//* Use, duplication or disclosure restricted by GSA ADP Schedule *
//* Contract with IBM Corp. *
//*********************************************************************
//* Sample JCL for execution server *
//* To Customize: *
//* ++LNGPRFX++: HLQ of Language Compiler *
//* ++LIBPRFX++: HLQ of Link Library *
//* ++SRCLIB++ : HLQ of COBOL Source Program *
//* ++COPYLIB++: HLQ of COBOL Copybook *
//* ++LOADLIB++: HLQ of Execution Module *
//* ++HBRHLQ++ : HLQ of Decision Server data set *
//* ++HBRWDS++ : HLQ of DS working data set *
//* ++PGM++ : Name of COBOL Calling Program *
//*********************************************************************
//CONFIG SET HBRHLQ=++HBRHLQ++
// SET HBRWDS=++HBRWDS++
// SET SRCLIB=++SRCLIB++
// SET CPYLIB=++COPYLIB++
// SET LOADLIB=++LOADLIB++
// SET MEM=++PGM++
//STEP1 EXEC PROC=IGYWCLG,
// LNGPRFX=++LNGPRFX++,
// LIBPRFX=++LIBPRFX++,
// PARM.COBOL='LIB'
//COBOL.SYSIN DD DISP=SHR,DSN=&SRCLIB(&MEM)
//COBOL.SYSLIB DD DISP=SHR,DSN=&CPYLIB
// DD DISP=SHR,DSN=&HBRHLQ..SHBRCOBC
//LKED.SYSLIB DD DSN=&LIBPRFX..SCEELKED,DISP=SHR
// DD DSN=&HBRHLQ..SHBRLOAD,DISP=SHR
//LKED.SYSLMOD DD DSN=&LOADLIB(&MEM),DISP=(MOD,KEEP),SPACE=(TRK,(3,3))
//GO.STEPLIB DD DISP=SHR,DSN=&LIBPRFX..SCEERUN
// DD DISP=SHR,DSN=&HBRHLQ..SHBRLOAD
//GO.SYSUDUMP DD SYSOUT=*
//GO.HBRPSNAP DD SYSOUT=*
//GO.HBRTMSGF DD DUMMY
//GO.HBRENVPR DD DISP=SHR,DSN=&HBRWDS..SHBRPARM(HBRBATCH)
さて、提供されるCOBOLバッチのソース、生成されたCOPYBOOKを元に、JCLのサンプルを使ってコンパイル/リンク/実行を行ってみます。
とりあえず、COBOLソース、COPYBOOK、JCL、ロードモジュールを配置するためのデータセットを以下の様に作成します。
ODM811.TEST.COBOL
ODM811.TEST.COPY
ODM811.TEST.JCLLIB
ODM811.TEST.LOADLIB
ソース、COPYBOOK、JCLを以下に配置します。
ソース: ODM811.TEST.COBOL(HBRMTUT2)
COPYBOOK: ODM811.TEST.COPY(HBRLDAT2)
JCL: ODM811.TEST.JCLLIB(HBRMTUT2)
実は提供されているCOBOLのソースはそのままだとうまく動きません。今回ルールをデプロイするときに自動でバージョン管理を行うようにしているのでバージョン情報が付いた状態でデプロイされています。その辺りの情報がソース中では反映されていないので、その部分を修正する必要があります。
まず、zRES上にデプロイされた呼び出し対象のルールセットのパスを確認します。
ブラウザからエクスプローラータブを開いて確認 ⇒ /SharingZMiniloan/1.0/SharingZMiniloan/1.0
COBOLのソースを修正します。具体的には以下のようにHBRA-CONN-RULEAPP-PATHに設定する値を上で確認したパスに変更します。
...
* Move ruleset parameters to table HBRA-RA-PARMETERS
MOVE ZERO TO HBRA-CONN-RETURN-CODES
MOVE LOW-VALUES TO HBRA-RA-PARMETERS
MOVE "/SharingZMiniloan/1.0/SharingZMiniloan/1.0"
TO HBRA-CONN-RULEAPP-PATH
...
ルール呼び出しのバッチを実行する際は、zRES接続情報などはソース中に埋め込むのではなく外部からパラメーターとして渡すことになります(上のソース中には具体的な接続先の情報などは指定していません)。そのzRES情報を設定するためのPDSメンバーは雛形が以下に生成されているのでそれをそのまま使います。
ODM811.WORK.O8B0.SHBRPARM(HBRBATCH)
中身を確認しておきます。
* The list of zRES sub system ids to connect to
HBRSSIDLIST=O8B1,O8B2
* Specifies the target for rule execution
HBRTARGETRES=ZRES
* Specifies the number of seconds to wait for a response
* from the zRule Execution Server stand alone
* 0 = No timeout
* 1 - 60000 = Seconds to wait for rule execution to complete
* (Use property HBRLOGTIMEOUTS in the HBRMSTR parms
* member to record client timeouts in the server's log)
HBRTIMEOUT=0
* Parameters relating to Trace
*
* ALL, FINE or FINEST: turn on client trace
* OFF: no trace
*
HBRTRACELEVEL=WARNING
コンパイル/リンク/実行用のJCLをカスタマイズします。コメントの内容に従って、環境に応じてHLQなどを設定していくイメージです。
//HBRMTUT2 JOB MSGCLASS=H,MSGLEVEL=(1,1),REGION=0M
// JCLLIB ORDER=(IGY630.SIGYPROC)
//*********************************************************************
//* Licensed Materials - Property of IBM *
//* 5655-Y31 *
//* Copyright IBM Corp. 2011, 2021. All Rights Reserved. *
//* U.S. Government Users Restricted Rights: *
//* Use, duplication or disclosure restricted by GSA ADP Schedule *
//* Contract with IBM Corp. *
//*********************************************************************
//* Sample JCL for execution server *
//* To Customize: *
//* ++LNGPRFX++: HLQ of Language Compiler *
//* ++LIBPRFX++: HLQ of Link Library *
//* ++SRCLIB++ : HLQ of COBOL Source Program *
//* ++COPYLIB++: HLQ of COBOL Copybook *
//* ++LOADLIB++: HLQ of Execution Module *
//* ++HBRHLQ++ : HLQ of Decision Server data set *
//* ++HBRWDS++ : HLQ of DS working data set *
//* ++PGM++ : Name of COBOL Calling Program *
//*********************************************************************
//CONFIG SET HBRHLQ=ODM811.TLIB
// SET HBRWDS=ODM811.WORK.O8B0
// SET SRCLIB=ODM811.TEST.COBOL
// SET CPYLIB=ODM811.TEST.COPY
// SET LOADLIB=ODM811.TEST.LOADLIB
// SET MEM=HBRMTUT2
//STEP1 EXEC PROC=IGYWCLG,
// LNGPRFX=IGY630,
// LIBPRFX=CEE,
// PARM.COBOL='LIB'
//COBOL.SYSIN DD DISP=SHR,DSN=&SRCLIB(&MEM)
//COBOL.SYSLIB DD DISP=SHR,DSN=&CPYLIB
// DD DISP=SHR,DSN=&HBRHLQ..SHBRCOBC
//LKED.SYSLIB DD DSN=&LIBPRFX..SCEELKED,DISP=SHR
// DD DSN=&HBRHLQ..SHBRLOAD,DISP=SHR
//LKED.SYSLMOD DD DSN=&LOADLIB(&MEM),DISP=(MOD,KEEP),SPACE=(TRK,(3,3))
//GO.STEPLIB DD DISP=SHR,DSN=&LIBPRFX..SCEERUN
// DD DISP=SHR,DSN=&HBRHLQ..SHBRLOAD
//GO.SYSUDUMP DD SYSOUT=*
//GO.HBRPSNAP DD SYSOUT=*
//GO.HBRTMSGF DD DUMMY
//GO.HBRENVPR DD DISP=SHR,DSN=&HBRWDS..SHBRPARM(HBRBATCH)
ちなみにこのJCLでは、コンパイル/リンク/実行を行うためのEnterprise COBOL提供プロシージャー"IGYWCLG"が使われています。
参考: Enterprise COBOL fro z/OS V6.3 - Compile, link-edit, and run procedure (IGYWCLG)
最終行のHBRENVPR DDで、実行時にアクセスするzRESの情報として先に確認したHBRBATCHというPDSメンバーを指定しています。
一通り準備ができたので、このJCLをサブミットします。
コンパイル/リンクが成功するとCOBOLバッチの実行が行われますので、JOBLOGのSYSOUTを見てみます。
connect zRules successful
invoke zRules successful
********** EXECUTION RESULT *********
Borrower Name : John
Loan Approved?: F
Reject messages:
The age exceeds the maximum or minimum.
**************************************
Disconnected zRules successful
ルール呼び出しが正常に行えたことが確認できました。