この章では、出口プログラムの記述方法について説明します。
ユーザー出口は MSS 自体におけるポイントであり、このポイントで制御をユーザー記述プログラムに移すことができ、そのプログラムの終了後は、このポイントから MSS が制御を再開できます。次のタイプのユーザー出口プログラムがサポートされています。
独立したグローバルおよびタスク関連ユーザー出口を記述する必要があります。ユーザー出口プログラムは、すべて非メインフレーム 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 つのコピーブックをインクルードする必要があります。
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.
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 コマンドを発行すると、アプリケーションから供給された情報を使用して入力パラメータが設定されます。そのパラメータは、次のとおりです。
| フィールド | 値 |
|---|---|
| esm-version-no | パラメータ・ブロックのバージョンを示します。Micro Focus は、更新されたインターフェイスを発行する場合にこの値をインクリメントします。 |
| esm-user-id | 現在のユーザーの ID。ユーザーがサインオンしていない場合、このフィールドにはバイナリーのゼロが含まれます。 |
| esm-opid | サインオン・テーブルで定義されている、ユーザーに関連付けられたオペレーター ID。ユーザーがサインオンしていない場合、このフィールドにはバイナリーのゼロが含まれます。 |
| esm-opclass | ユーザーに関連付けられたオペレーター・クラス。このフィールドには、ユーザーがサインオンしている場合は文字のゼロ、サインオンしていない場合はバイナリーのゼロが含まれます。 |
| esm-arg-01-flag | 未使用。 |
| esm-arg-02-flag | 値 1 は、アプリケーションが RESTYPE キーワードを使用したことを示します。esm-restype フィールドには、有効なリソース・タイプが含まれます。 |
| esm-arg-03-flag | 値 1 は、アプリケーションが RESID キーワードを使用したことを示します。これは必須であるため、このフィールドは常に 1 に設定されます。esm-resid フィールドを参照してください。 |
| esm-arg-04-flag | 値 1 は、アプリケーションが RESIDLENGTH キーワードを使用したことを示します。esm-residlength フィールドを参照してください。 |
| esm-arg-05-flag | 値 1 は、アプリケーションが READ キーワードを使用したことを示します。esm-read フィールドを参照してください。 |
| esm-arg-06-flag | 値 1 は、アプリケーションが UPDATE キーワードを使用したことを示します。esm-update フィールドを参照してください。 |
| esm-arg-07-flag | 値 1 は、アプリケーションが RESCLASS キーワードを使用したことを示します。esm-resclass フィールドには、リソース・クラスが含まれます。 |
| esm-arg-08-flag | 値 1 は、アプリケーションが ALTER キーワードを使用したことを示します。esm-alter フィールドを参照してください。 |
| esm-arg-09-flag | 値 1 は、アプリケーションが CONTROL キーワードを使用したことを示します。esm-control フィールドを参照してください。 |
| esm-arg-10-flag | 値 1 は、アプリケーションが LOGMESSAGE または LOG キーワードを使用したことを示します。esm-logmessage フィールドを参照してください。 |
| esm-arg-11-flag | 未使用。 |
| esm-arg-12-flag | 未使用。 |
| esm-arg-13-flag | 未使用。 |
| esm-arg-14-flag | 未使用。 |
| esm-arg-15-flag | 未使用。 |
| esm-arg-16-flag | 未使用。 |
| esm-restype | 指定した場合、このフィールドには次のいずれかの値が含まれます。
|
| esm-resclass | 指定した場合、このフィールドにはリソース・クラスの名前が含まれます。 |
| esm-residlength | 指定した場合、このフィールドには、esm-resid フィールド内の有効な文字の数が含まれます。 |
| esm-resid | このフィールドには、リソースの ID が含まれます。アプリケーションでは、そのリソースに対するユーザーのアクセスを問い合わせる必要があります。リソースの ID は、最大 12 文字の CICS リソース ID、または最大 240 文字のユーザー定義リソース ID にすることができます。 |
| esm-logmessage | 指定した場合は、このフィールドによって、セキュリティー違反をログ記録するかどうかがユーザー出口プログラムに通知されます。メインフレームでは、このフィールドは、セキュリティー違反をログ記録するように CICS に命じるために使用されます。このフィールドはメインフレームとの互換性のために用意されていますが、セキュリティー違反はログ記録されません。 |
ユーザー出口プログラムは、出力パラメータを設定します。その出力パラメータは、次のとおりです。
| フィールド | 値 |
|---|---|
| esm-eibresp | このフィールドには、QUERY SECURITY の呼び出しが有効であることを示すゼロ、または有効でないことを示す非ゼロ値が含まれます。この値は、EIBRESP フィールドでアプリケーション・プログラムに返されます。ここに正しい値が格納されるようにするのは、ユーザー出口プログラムの責任です。NOTFND または QIDERR 状態だけを返す必要がありますが、そうするように制限されているわけではありません。 |
| esm-eibresp2 | 出口プログラムが esm-eibresp フィールドでゼロ以外の値を返す場合、その出口プログラムはこのフィールドでもゼロ以外の値を返す必要があります。出口プログラムが返す必要のある値は、NOTFND 状態の場合は 1、3、5、8 のいずれか、QIDERR 状態の場合は 1 です。この値は、EIBRESP2 フィールドでアプリケーションに返されます。 |
| esm-eibrcode | 出口プログラムが esm-eibresp フィールドでゼロ以外の値を返す場合、その出口プログラムはこのフィールドに 16 進値を格納する必要があります。この値は、EIBRCODE フィールドでアプリケーション・プログラムに返されます。 |
| esm-alter | アプリケーションが名前付きリソースの ALTER ステータスを要求した場合 (esm-arg-08-flag フィールドがセットされる)、出口プログラムは ALTERABLE または NOTALTERABLE の CVDA 値をこのフィールドで返す必要があります。 |
| esm-control | アプリケーションが名前付きリソースの CONTROL ステータスを要求した場合 (esm-arg-09-flag フィールドがセットされる)、出口プログラムは CTRLABLE または NOTCTRLABLE の CVDA 値をこのフィールドで返す必要があります。 |
| esm-read | アプリケーションが名前付きリソースの READ ステータスを要求した場合 (esm-arg-05-flag フィールドがセットされる)、出口プログラムは READABLE または NOTREADABLE の CVDA 値をこのフィールドで返す必要があります。 |
| esm-update | アプリケーションが名前付きリソースの UPDATE ステータスを要求した場合 (esm-arg-06-flag フィールドがセットされる)、出口プログラムは UPDATABLE または NOTUPDATABLE の CVDA 値をこのフィールドで返す必要があります。 |
注：入力パラメータ・ブロックの文字フィールドは、EBCDIC プログラムから生じたものであっても、すべて ANSI でエンコードされます。EBCDIC のデータが必要な場合は、データを変換する必要があります。詳細については、『プログラム開発』の各ロケール対応の章を参照してください。
QUERY SECURITY コマンドが発生すると、そのコマンドは妥当性が検査され、場合によっては、いずれかのエラー状態を返すことがあります。コマンドが妥当性検査に合格した場合は、入力フィールドがセットアップされ、制御がユーザー出口プログラムに渡されます。ユーザー出口プログラムは、それ自身で何らかの妥当性検査を実行し、要求を拒否する場合があります。
返すことができるエラー状態を次の表に示します。
| エラー状態 (EIBRESP フィールド) | 詳細情報 (EIBRESP2 フィールド) | |
|---|---|---|
| INVREQ | 7 | LOGMESSAGE に LOG または NOLOG が含まれていません。 |
| 9 | RESID が無効であるか、またはブランクで埋まっています。 | |
| 10 | 外部セキュリティー・マネージャー (ESM) が非アクティブであるか、または存在しません。これは、ユーザー出口プログラムがなくなっていることを意味します。 | |
| LENGERR | 6 | RESIDLENGTH 値が無効です。つまり、1～246 の範囲内にありません。 |
| NOTFND | 2 | RESTYPE 値が無効です。 |
出口プログラムでチェックする必要性が最も高いと思われるエラー状態を次の表に示します。
| エラー状態 (EIBRESP フィールド) | 詳細情報 (EIBRESP2 フィールド) | |
|---|---|---|
| NOTFND | 1 | RESID 値が無効です。 |
| 3 | RESTYPE (SPCOMMAND) の RESID 値が無効です。 | |
| 5 | 外部セキュリティー・マネージャー (ESM) に対して RESCLASS が定義されていません。 | |
| 8 | リソースが保護されていません。これは、QUERY SECURITY を RESCLASS オプションと共に使用した場合にのみ返されます (RESTYPE を使用した場合は返されない)。 | |
| QIDERR | 1 | 指定された RESID に関連付けられている間接キュー名が見つかりません。 |
エラー処理を行わないアプリケーション・プログラムに上記のいずれかのエラー・コードが返された場合、そのアプリケーションは異常終了します。