CBL_CANCEL_PROC
プログラムの取消しを制御する。
構文:
call "CBL_CANCEL_PROC" using by value function by reference parameter-block by value cblte-cppb-userdata-length returning status-code
パラメーター：
| 呼び出しプロトタイプ使用時 ( 説明の読み方) | PIC (32 ビット システム) | ||||
|---|---|---|---|---|---|
| function | cblt-x4-comp5 | pic x(4) comp-5. | |||
| parameter-block | Group predefined as cblt_cancel_proc_params containing: | 以下を含む集団項目: | |||
| cblte-cppb-version | cblt-x4-comp5 | pic x(4) comp-5 value 0. | |||
| cblte-cppb-flags | cblt-x4-comp5 | pic x(4) comp-5. | |||
| cblte-cppb-callback | cblt-ppointer | usage procedure-pointer. | |||
| cblte-cppb-handle | cblt-pointer | usage pointer. | |||
| cblte-cppb-userdata | cblt-pointer | usage pointer. | |||
| cblte-cppb-priority | cblt-x4-comp5 | pic x(4) comp-5. | |||
| cblte-cppb-userdata-length | cblt-x4-comp5 | pic x(4) comp-5. | |||
| status-code | 説明の読み方. | ||||
入力パラメーター：
| function | 次のいずれか1つを設定する。
上記以外の値は、今後の拡張のために予約されている。 |
||||||||||
| cblte-cppb-version | パラメーターブロックのバージョン。ここで記述するパラメーターブロックでは、本フィールドをゼロに設定すること。 |
||||||||||
| cblte-cppb-flags | 現時点では未定義。ゼロに設定すること。 |
||||||||||
| cblte-cppb-callback | 設定可能な値は次のとおり。
|
||||||||||
| cblte-cppb-handle | 設定可能な値は次のとおり。
|
||||||||||
| user-data | 設定可能な値は次のとおり。
|
||||||||||
| cblte-cppb-priority | 設定可能な値は次のとおり。
|
||||||||||
| user-data-length | 設定可能な値は次のとおり。
|
出力パラメーター：
| cblte-cppb-version | 無視される。 |
||||||||||
| flags | 無視される。 |
||||||||||
| cblte-cppb-callback | 無視される |
||||||||||
| cblte-cppb-handle | 設定可能な値は次のとおり。
|
||||||||||
| cblte-cppb-userdata | 無視される。 |
||||||||||
| cblte-cppb-priority | 無視される。 |
||||||||||
| status-code |
|
説明:
本ルーチンは、COBOLプログラムがそれ自身のまたは他のCOBOLプログラムが取り消されそうであるという通知を受けられるような機構を提供する。
この通知により、COBOLプログラムはリソースの使用をやめ、割り当てを解除する。リソースはプログラムの実行中にプログラムによって割り当てられたものであり、COBOLランタイム システムまたはオペレーティングによって自動的に扱われない。リソースは、通常はオペレーティング システムまたはランタイム システムによって提供されるが、アプリケーション内の他のモジュールによって提供されるリソースもある。
COBOLランタイム システムは、取り消されるプログラムに関連するリスト（取消しリスト）を処理することによって通知する。そのため、通知を可能にするには、COBOLランタイム システムに取消しリストに記述項を作成するように命令する必要がある。取消しリストの記述項の管理がCBL_CANCEL_PROCの目的である。
取消しリストに記述項を作成するために、CBL_CANCEL_PROCは次の3つの事項を知る必要がある。
- どのプログラムがいつ取り消され、通知のきっかけとなるのか。プログラムは、プログラムハンドル（パラメーター「ハンドル」によって記述項に設定）によって識別される。
- 呼び出す取消しルーチン。取消しルーチンは、プログラムが取り消されるときに呼び出される入口点です。
- 取消し優先順位。この通知用の優先順位。
パラメーター「機能」に0または1を設定すると、ランタイム システムが情報を提供する。これにより、プログラムハンドルに関連する取消しリストに記述項を作成する。記述項は、通知を受けるときに取消しルーチンを呼び出すように指定する。リストの位置は、取消し優先順位の値によって決まる。
出口上の「ハンドル」パラメーターで指定する登録呼び出しによって返された値を使用すると、作成された取消しリストの記述項を参照する。これにより、プログラムは本ルーチンに2、3、または4を指定した本ルーチンを使用し、後で登録を修正したりリストから削除する。
プログラムハンドルの取得
プログラムハンドルは、固有の値であり、COBOLランタイム システムはこれを取消し可能なものと関連付ける。そのため、あるCOBOLプログラムにおけるすべての入口点は同じプログラムハンドルを共有するので、COBOLプログラムの入口点を取り消すとそのプログラム内のすべての入口点が取り消される。
CBL_CANCEL_PROCルーチンを使用する基本的な方法が2つあり、どちらかの方法を必要とするかによって、プログラムが現行のプログラムハンドルを取得するために必要な作業量も違う。以下に2つの方法を説明する。
ローカル登録
プログラムが取り消されるという通知の受取りを望んでいる場合には、ローカル登録をすることができる。これは通常そのコードで1回だけ行う。この登録方法では、プログラムはプログラムハンドルとしてナルを渡すだけでよい。そうすると、CBL_CANCEL_PROCルーチンは自動的に現行のプログラムハンドルを設定して正しいリストに記述項を作成する。
通常、ローカル登録で指定された取消しルーチンは、登録プログラムにおける入口点。
プログラムの例として、オペレーティング システムから直接受け取ったいくらかのリソースを割り当てたプログラム、取り消される前にリソースの割り当てを解除する機会が必要であったプログラムなどがある。
サービス登録
これは、ローカル登録よりも少し複雑な登録方法である。この方法を使用するのは、サービスプログラム（つまり、他のCOBOLプログラムのためにリソースを管理するプログラム）がクライアントが取り消されるという通知の受取りを必要とする場合である。この登録方法では、プログラムハンドルはCBL_GET_PROGRAM_INFOルーチンを呼び出すことによって取得できる。CBL_GET_PROGRAM_INFOルーチンに渡すパラメーターは、どの機能を必要とするかにより異なる。最も一般的な使用法は、CBL_GET_PROGRAM_INFOルーチンの機能2を使用して呼び出しプログラムのプログラムハンドルを取得する方法である。
通常、サービス登録で指定された取消しルーチンは、登録プログラムにおける入口点である。
このプログラムの例として、他のCOBOLプログラムのためにファイルを開いたり管理したりするファイル ハンドラーモジュールなどがある。指定されたプログラムが取り消されると、そのプログラムのために開かれたファイルはすべてCOBOLの定義に従って自動的に閉じられる。
この例は、ファイルを開くプログラムとファイルを閉じるだけのプログラムにローカル登録を行うことによっても可能である。ただし、この場合エラーが発生しやすく、COBOLの定義には準拠しないし、乱雑な方法ともいえる。
CBL_CANCEL_PROCルーチンをサービスプログラムで使用する場合に重要なことは、適切なリソースがクライアントプログラムによって解放されるならば、通知はクライアントプログラムの取消しリストから削除される。｢機能」に3または4を設定して行う。これを効率的に行うために、サービスプログラムは「機能」に0または1を設定したときに返されたプログラムハンドルをリソース構造体に格納する。そのため、「機能」に3または4を設定したときに登録ハンドルとして返されるように簡単にプログラムハンド。
サービスプログラムが機能3または4を使用した登録解除に失敗した場合、クライアントプログラムが取り消されるときに仮の通知が発生し、予測できない結果となる。
ユーザーデータ
CBL_CANCEL_PROCによって要求された3つの必須情報（つまり、「機能」に0または1を設定することにより得られるプログラムハンドル、取消しルーチン、および取消し優先順位）のほかに、オプションでユーザーデータも受け入れられる。
｢ユーザーデータ」パラメーターを使用すると、取消しルーチンを登録するプログラムはプログラムが取り消されたという通知を受けるときに取消しルーチンに渡すパラメーターを指定することができる。登録ごとに異なる「ユーザーデータ」パラメーターを指定することができ、また複数の登録に同じ「ユーザーデータ」パラメーターを指定することもできる。さらに、「ユーザーデータ長」パラメーターにゼロ以外の値を指定することによって、「ユーザーデータ」パラメーターをコピー（このコピーがパラメーターとして取消しルーチンに渡される）するように指定すること もできる。
この機能は、サービスプログラムでとても役に立つ。サービスプログラムはクライアントプログラムをサービス「ハンドル」と関連付けるためにリストを管理する必要がない。ただし、CBL_CANCEL_PROC登録プロセスに「ユーザーデータ」パラメーターとして「ハンドル」を渡してあるならば、取消しルーチンに渡すパラメーターとしてサービス「ハンドル」を直接受け取ることはできる。
ゼロ以外のユーザーデータ長パラメーターの指定
「ユーザーデータ長」パラメーターには、ゼロよりもゼロ以外の値を設定した方が便利である。ただし、これは一般的にはユーザーデータ領域が小さい場合のみ。「ユーザーデータ長」パラメーターにゼロ以外の値を設定すると、「ユーザーデータ」パラメーターのアドレスから指定されたバイト数がコピーされ、そのコピーはりストの記述項に保持される。あるプログラムハンドルに関連するプログラムが取り消された場合、取消しルーチンはパラメーターとしてユーザーデータ領域のコピーを受け取る。そのコピーは取消しルーチンが戻ったときにCOBOL実行時シス テムによって削除される。
CBL_CANCEL_PROCルーチンは渡されたユーザーデータ領域の構造については何も知らず、ただフラットメモリブロックをコピーするだけであるということに注意すること。たとえば、ブロック内に埋め込まれたUSAGE POINTERの項目はコピーされますが、その項目はメモリを指さない。この場合は、アプリケーションがデータ構造全体を割り当ててコピーし、そのコピーを値がゼロのユーザーデータ長を使用して渡した方がよい。
ゼロのユーザーデータ長パラメーターの指定
「ユーザーデータ長」パラメーターにゼロを設定すると（これにより登録プロセスに指定された元の「ユーザーデータ」パラメーターが取消しルーチンに渡される。）、取消しルーチンがブロック内のすべてのデータ構造を削除するかその割り当てを解除する。
この方法を使用して「ユーザーデータ」パラメーターを渡す場合には、とりわけ同じユーザーデータ領域が複数の登録ハンドル（登録ハンドルは、「ハンドル」パラメーターによって出口上に返される）に登録される場合は特に注意が必要である。次のことに気を付けること。割り当てられたリソースを解除する場合は1度だけ行うこと、割り当てられたリソースを関連する登録ハンドルの最後が壊れるまで有効な状態に保つことの2点。これを実現するには、通常はユーザーデータ領域のどこかに「使用回数」フィールドを置きます。「使用回数」は「ユーザーデータ」パラメーターが登録ハンドルに登録されるたびに数字を1づつ加算し、取消しルーチンが「ユーザーデータ」パラメーターを指定して呼び出されるたびに数字を1づつ減算する。
優先順位
優先順位（機能1を使用すると設定される）は、ユーザーコードに対して0から127までの値。200から209までの値の優先順位は、ファイル ハンドラーでは逆順の意味に取られる。これ以外の値を優先順位に指定すると、予期できない結果となる。たいていのアプリケーションでは、省略値の64は使用できる。
取消しルーチンの実行
ここでは、CBL_CANCEL_PROCで導入する場合に適した取消しルーチンの実行方法について説明する。
working-storage section.
01 cancel-status pic x(4) comp-5.
linkage-section.
01 cancel-reason pic x(4) comp-5.
01 cancel-flags pic x(4) comp-5.
01 program-id usage pointer.
01 user-data usage pointer.
procedure division.
entry "user-cancel-routine" using by value cancel-reason
by value cancel-flags
by value program-id
by value user-data.
cancel-routine section.
cancel-routine-para.
*> This is where the code which handles the CANCEL-notification goes.
*> The user-data field specified in the registration is passed to us here,
*> along with the program-id of the program being cancelled.
*> Iff this routine is handling registrations which specified a
*> user-data-field length of zero, then the memory pointed to by user-data
*> may also need to be freed before returning.
exit program returning cancel-status.
cancel_reasonパラメーターには、取消しの理由を記述する。次のように設定できる。
ビット0（値1） 取消しは、STOP RUN処理による。
ビット6（値64） 取消しは、導入解除（「機能」に4を設定してCBL_CANCEL_PROCを呼び出した場合）による。
これ以外のビットはすべて予約済みであり、設定しても無視される。
cancel_flagsパラメーターは現在予約済みであり、設定しても無視される。
関連項目