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 (32bitシステム) | ||||
|---|---|---|---|---|---|
| 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パラメタは現在予約済みであり、設定しても無視される。
関連項目