出口プログラムの開発

この章では、出口プログラムの記述方法について説明します。

概要

ユーザー出口は MSS 自体におけるポイントであり、このポイントで制御をユーザー記述プログラムに移すことができ、そのプログラムの終了後は、このポイントから MSS が制御を再開できます。次のタイプのユーザー出口プログラムがサポートされています。

• グローバル出口プログラム。グローバル・ユーザー出口は、特定の CICS タスクに関連していないコード内のポイントです (例えば、アプリケーション・プログラムに制御が移される前)。次のタイプのグローバル・ユーザー出口がサポートされています。
  • XZCATT
  • XZCIN
  • XZCOUT
  • XEIIN
  • XEOUT
• タスク関連出口プログラム。タスク関連ユーザー出口は、ロールバックやコミットなどのタスク関連の関数を処理するコード内のポイントです。
• セキュリティー出口プログラム。セキュリティー出口プログラムは、QUERY SECURITY CICS コマンドの動作をエミュレートするように記述された出口プログラムです。

独立したグローバルおよびタスク関連ユーザー出口を記述する必要があります。ユーザー出口プログラムは、すべて非メインフレーム COBOL で記述してください。ユーザー出口プログラムでは、EXEC CICS コマンドを使用せず、また、ネイティブのアドレス指定をポインターに使用する必要があります。

グローバルおよびタスク関連出口プログラム

アプリケーション・プログラムに必要な各ユーザー出口は、その出口が呼び出される前に有効にする必要があります。アプリケーション・プログラムがユーザー出口の使用を終了したら、そのユーザー出口を無効にすることができます。ただし、ユーザー出口を無効にする必要性はありません。CICS の起動時には、ユーザー出口は常にデフォルトで無効になります。ユーザー出口プログラムを有効にする場合は CICS コマンド ENABLE PROGRAM を使用し、無効にする場合は CICS コマンド DISABLE PROGRAM を使用します。不正な出口を有効にしようとすると、X'804000' の EIBRCODE が返されます。正当であるが実装されていない出口を有効にしようとすると、X'804010' の EIBRCODE が返されます。また、EXTRACT EXIT コマンドも用意されています。ユーザー出口プログラムの作業領域にアクセスするには、このコマンドを使用します。 これらのコマンドに提供されるサポートのレベルの詳細については、System Programmers Commands のトピックを参照してください。

各ユーザー出口プログラムは、プログラムとして (PLT で) 定義する必要があり、その定義は稼働中のシステムで利用できなければなりません。

グローバル・ユーザー出口とタスク関連ユーザー出口については、IBM の CICS/ESA 3.3 Customization Guide を参照してください。このマニュアルには、正当なユーザー出口ポイントの一覧が記載されています。

ユーザー出口プログラムには、それがグローバル・ユーザー出口とタスク関連ユーザー出口のどちらを対象としているかに関わらず、次の 2 つのコピーブックをインクルードする必要があります。

• dfhcbuxi.cpy：

        78 78-uxi-TRUE                          value  1.
          78 78-uxi-XZCATT                        value  2.
          78 78-uxi-XZCIN                         value  3.
          78 78-uxi-XZCOUT                        value  4.
          78 78-uxi-XEIIN                         value  5.
          78 78-uxi-XEIOUT                        value  6.
        ***--------------------------------------------------------------*
        ***  Base parameters                                             *
        ***--------------------------------------------------------------*
          01 uxi-user-exit-interface.
             02 uxi-operational-flags-ptr         pointer.
             02 uxi-scheduling-flags-ptr          pointer.
             02 uxi-global-area-ptr               pointer.
             02 uxi-global-area-length            pic x(4) comp-5.
             02 uxi-local-area-ptr                pointer.
             02 uxi-local-area-length             pic x(4) comp-5.
             02 uxi-dfheiblk-ptr                  pointer.
             02 uxi-unit-of-recovery-ptr          pointer.
        ***--------------------------------------------------------------*
        ***  Exit specific parameters                                    *
        ***--------------------------------------------------------------*
             02 uxi-exit-specific-ptrs.         *> XZCATT In/Out XEin/out
              03 uxi-resource-ptr      pointer. *> TCTTE  TCTTE  Arg list
              03 uxi-resource-data-ptr pointer. *> TIOA   TIOA   user-id
              03 uxi-res-data-len-ptr  pointer. *>  *      *
              03 uxi-aux-1-ptr         pointer. *> APPC          program
              03 uxi-aux-1-length-ptr  pointer. *>  *
              03 uxi-aux-2-ptr         pointer. *> Tran          Sys EIB
              03 uxi-aux-2-length-ptr  pointer. *>
              03 uxi-aux-3-ptr         pointer. *> TEUA   TEUA
              03 uxi-aux-3-length-ptr  pointer. *>  *      *
              03 uxi-aux-4-ptr         pointer. *> ComA   ComA
              03 uxi-aux-4-length-ptr  pointer. *>  *      *
              03                       pointer. *>
        ***--------------------------------------------------------------*
        ***  System parameters                                           *
        ***--------------------------------------------------------------*
             02 uxi-PCA-ptr                       pointer.
             02 uxi-CSA-ptr                       pointer.
             02 uxi-DCA-ptr                       pointer.
             02 uxi-local-trace-table-ptr         pointer.
  

• dfhcbuxc.cpy：

          01 lk-uxc-operation.
             03 lk-uxc-exit-id                   pic x comp-x.
                88 lk-uxc-TRUE-88                value 78-uxi-TRUE.
                88 lk-uxc-XZCATT-88              value 78-uxi-XZCATT.
                88 lk-uxc-XZCIN-88               value 78-uxi-XZCIN.
                88 lk-uxc-XZCOUT-88              value 78-uxi-XZCOUT.
                88 lk-uxc-XEIIN-88               value 78-uxi-XEIIN.
                88 lk-uxc-XEIOUT-88              value 78-uxi-XEIOUT.
             03 lk-uxc-schedule                  pic x.
                88 lk-uxc-generic-88             value x'80'.
                88 lk-uxc-TRUE-on-start-88       value x'80'.
                88 lk-uxc-TRUE-on-sync-88        value x'40'.
                88 lk-uxc-TRUE-on-prep-88        value x'20'.
                88 lk-uxc-TRUE-on-tr-wrap-88     value x'01'.
             03 lk-uxc-modifier                  pic x    comp-x.
                88 lk-uxc-user-syncpoint-88      value 0.
                88 lk-uxc-task-syncpoint-88      value 1.
                88 lk-uxc-task-start-88          value 2.
                88 lk-uxc-initialization-88      value 254.
                88 lk-uxc-shutdown-88            value 255.
             03 lk-uxc-action                    pic x    comp-x.
                88 lk-uxc-syncpoint-commit-88    value 0.
                88 lk-uxc-syncpoint-rollback-88  value 1.
                88 lk-uxc-syncpoint-prepare-88   value 2.
             03 lk-uxc-return-code               pic x(4) comp-5.
  
          01 lk-uxc-schedule-parm.
             03 lk-uxc-schedule-byte             pic x.
             78 78-lk-uxc-TRUE-on-start          value x'80'.
             78 78-lk-uxc-TRUE-on-sync           value x'40'.
             78 78-lk-uxc-TRUE-on-prep           value x'20'.
             78 78-lk-uxc-TRUE-on-tr-wrap        value x'01'.
  

タスク関連ユーザー出口プログラムの骨組みの例を次に示します。

       id division.
       program-id. samptrue.
       environment division.
       configuration section.
       input-output section.
       data division.
       file section.
       working-storage section.
       01 work-scl.
           02 ws-allocate-local.
              03 ws-allocate-local-ptr-x.
                 04 ws-allocate-local-ptr       pointer.
              03 ws-allocate-local-size         pic x(4) comp-5.
              03 ws-allocate-local-return       pic x(4) comp-5.
                 88 ws-allocate-local-ok-88        value 0.
                 88 ws-allocate-local-no-space-88  value 1.
                 88 ws-deallocate-local-invalid-88 value 2.
                 88 ws-deallocate-inv-length-88    value 157.
           02 ws-allocate-local-type            pic x.
           02                                   pic x.
           02 ws-mfpm-register-flag             pic x(2).
              88 ws-mfpm-assign-24-88              value x'0000'.
              88 ws-mfpm-absolute-24-88            value x'0200'.
              88 ws-mfpm-assign-31-88              value x'0001'.
              88 ws-mfpm-absolute-31-88            value x'0201'.
           02 ws-mfpm-allocate-size             pic x(4) comp-x.
           02 ws-mfpm-allocate-ptr-x.
              03 ws-mfpm-allocate-ptr           pointer value null.
       linkage section .
       copy 'dfhcbuxi.cpy'.
       copy 'dfhcbuxc.cpy'.
       01 lk-global-area.
           03 lk-ga-byte pic x occurs 0 to 4096
               depending on uxi-global-area-length.
       01 lk-local-area.
           03 lk-la-byte pic x occurs 0 to 4096
               depending on uxi-local-area-length.
       procedure division using
                           uxi-user-exit-interface.
       module-entry-point.
           move 0                      to return-code
           set address of lk-uxc-operation 
               to uxi-operational-flags-ptr
           set address of lk-uxc-schedule-parm
               to uxi-scheduling-flags-ptr
           move 0                      to lk-uxc-return-code
           *> -- Are we being called by an application?
           *> -- (User application sets unused value in lk-uxc-schedule.) 
           if lk-uxc-schedule = x'02'
               perform called-by-application
               goback
           end-if
           *> -- Register syncpoint interest
           move 78-lk-uxc-TRUE-on-sync to lk-uxc-schedule-byte
           *> -- Register start of task interest
           call "CBL_OR" using 
               78-lk-uxc-TRUE-on-start
               lk-uxc-schedule-byte
               by value 1
           end-call
           *> -- Register any other interest here by OR'ing bits
           *> -- in lk-uxc-schedule-byte as above.
           if lk-uxc-exit-id not = 0 *> -- handle only TRUEs
               goback
           end-if
           evaluate true
           when lk-uxc-initialization-88
           when lk-uxc-shutdown-88
               goback
           when lk-uxc-task-start-88
               perform save-TA-address
           when lk-uxc-task-syncpoint-88
               perform end-task-process
           when lk-uxc-user-syncpoint-88
               set address of lk-global-area 
                   to uxi-global-area-ptr
               set address of lk-local-area 
                   to uxi-local-area-ptr
               evaluate true
               when lk-uxc-syncpoint-prepare-88
                   *> -- We haven't registered an interest for this
                   continue
               when lk-uxc-syncpoint-commit-88
                   perform commit-process
               when lk-uxc-syncpoint-rollback-88
                   perform rollback-process
               end-evaluate
           end-evaluate
           goback
           .
       called-by-application section.
           *> -- Add any code here that you wish to execute when
           *> -- called by an application program.
           *> -- This sample passes back the address of the local 
           *> -- task area.
           set uxi-local-area-ptr      to ws-mfpm-allocate-ptr
           exit
           .
       save-TA-address section.
           *> -- Convert local task area address and save in W/S.
           exit
           .
       end-task-process section.
           *> -- Insert code here that you wish to perform at
           *> -- end of task.
           exit
           .
       commit-process section.
           *> -- Insert code here that you wish to perform at 
           *> -- user syncpoint.
           exit
           .
       rollback-process section.
           *> -- Insert code here that you wish to perform at 
           *> -- user backout.
           exit
           .

セキュリティー出口プログラム

MSS は、ユーザー出口プログラムの呼び出しによって QUERY SECURITY CICS コマンドの動作をエミュレートします。メインフレームでは、QUERY SECURITY コマンドは、IBM の RACF などの外部セキュリティー・マネージャー (External Security Manager; ESM) に問い合わせて、特定のエンドユーザーに許可される特定のリソースへのアクセスのレベルに関する情報をアプリケーションに返します。ユーザー出口プログラムは、これと同じ情報を返す必要があります。

デフォルトのユーザー出口プログラムが提供されており、このプログラムはすべてのタイプのアクセスについて NOT を返すよう設定されています。つまり、CICS アプリケーションが QUERY SECURITY コマンドを発行した場合、その結果としてアクセスは常に拒否されます。他の動作にしたい場合は、提供された出口プログラムを変更する必要があります。

インターフェイス

ユーザー出口プログラムの名前は dfhuesm にする必要があります。サンプル・プログラムの dfhuesm.cbl、および MSS と出口プログラムの間で渡されるパラメータを定義しているコピーブック dfhuesm.cpy は、$COBDIR/cpylib フォルダーに用意されています。

QUERY SECURITY コマンドを発行すると、アプリケーションから供給された情報を使用して入力パラメータが設定されます。そのパラメータは、次のとおりです。

ユーザー出口プログラムは、出力パラメータを設定します。その出力パラメータは、次のとおりです。

エラー状態

QUERY SECURITY コマンドが発生すると、そのコマンドは妥当性が検査され、場合によっては、いずれかのエラー状態を返すことがあります。コマンドが妥当性検査に合格した場合は、入力フィールドがセットアップされ、制御がユーザー出口プログラムに渡されます。ユーザー出口プログラムは、それ自身で何らかの妥当性検査を実行し、要求を拒否する場合があります。

返すことができるエラー状態を次の表に示します。

出口プログラムでチェックする必要性が最も高いと思われるエラー状態を次の表に示します。

エラー処理を行わないアプリケーション・プログラムに上記のいずれかのエラー・コードが返された場合、そのアプリケーションは異常終了します。