CBL_CANCEL_PROC

call "CBL_CANCEL_PROC" using by value function
                       by reference   parameter-block
                       by value       cblte-cppb-userdata-length
                       returning      status-code

パラメーター

function

呼び出しプロトタイプ (「説明の読み方」を参照)：cblt-x4-comp5

PIC：pic x(4) comp-5

parameter-block

cblt-cancel-proc-params として定義されている集団 (以下を含む)

01 cblt-cancel-proc-params      typedef.	
    03 cblte-cppb-version       cblt-x4-comp5. *> pic x(4) comp-5 value 0.
    03 cblte-cppb-flags         cblt-x4-comp5. *> pic x(4) comp-5.
    03 cblte-cppb-callback      cblt-ppointer  *> usage procedure-pointer.
    03 cblte-cppb-handle        cblt-pointer   *> usage pointer.
    03 cblte-cppb-userdata      cblt-pointer   *> usage pointer.
    03 cblte-cppb-priority      cblt-x4-comp5. *> pic x(4) comp-5.

cblte-cppb-userdata-length

呼び出しプロトタイプ (「説明の読み方」を参照)：cblt-x4-comp5

PIC：pic x(4) comp-5

status-code

「説明の読み方」を参照。

説明

このルーチンは、COBOL プログラムに対して、その COBOL プログラム自体または別の COBOL プログラムがキャンセルされるときに事前に通知するためのメカニズムを提供します。

この通知により、COBOL プログラムが実行中に割り当てたリソースで、COBOL ランタイム システムまたはオペレーティング システムによる自動処理が行われていないリソースについて、COBOL プログラムでの使用を終了し、割り当てを解除することができます。これらは、通常はオペレーティング システムまたはランタイム システムから提供されたリソースですが、アプリケーション自体の別のモジュールから提供されたリソースも含まれることがあります。

COBOL ランタイム システムでは、キャンセルされるプログラムに関連付けられたリスト (キャンセル リスト) を処理することによって通知を行います。そのため、通知を有効にするには、キャンセル リストにエントリを作成するように COBOL ランタイム システムに指示する必要があります。このキャンセル リストのエントリを管理することが CBL_CANCEL_PROC の目的です。

キャンセル リストにエントリを作成するために、CBL_CANCEL_PROC には次の 3 つの情報が必要です。

• キャンセルされたときに通知をトリガーするプログラム。このプログラムは、プログラム ハンドル (入力時にパラメーター cblte-cppb-handle で設定) によって識別されます。
• 呼び出す cblte-cppb-callback。cblte-cppb-callback は、プログラムがキャンセルされたときに呼び出されるエントリ ポイントです。
• キャンセル優先度。この通知の優先度です。

この情報は、パラメーター function を 0 または 1 に設定するとランタイム システムに提供されます。これにより、プログラム cblte-cppb-handle に関連付けられたキャンセル リストにエントリが作成され、そのエントリに従って通知の発生時に cblte-cppb-callback が呼び出されるようになります。リスト内の位置はキャンセル優先度の値によって決まります。

作成されたキャンセル リストのエントリは、登録呼び出しの終了時に cblte-cppb-handle パラメーターで返される値を使用して参照できます。これにより、function を 2、3、または 4 に設定してこのルーチンを使用することで、後で登録を変更することができます。たとえば、登録の優先度を変更したり、リストから削除したりすることができます。

プログラム ハンドルは、COBOL ランタイム システムによってキャンセル可能なエンティティに関連付けられる一意の値です。COBOL プログラムのすべてのエントリ ポイントで同じプログラム ハンドルを共有するため、COBOL プログラムのいずれかのエントリ ポイントをキャンセルすると、そのプログラムのすべてのエントリ ポイントがキャンセルされます。

CBL_CANCEL_PROC ルーチンを使用する基本的な方法は 2 種類あり、どちらの方法が必要であるかによって、正しいプログラム ハンドルを取得するためにプログラムで必要となる作業量が異なります。

ローカル登録

そのプログラム自体がキャンセルされるときに通知を受け取る場合は、ローカル登録を使用できます。通常、これはそのコードで 1 回だけ行います。この登録方法の場合、プログラムで必要な作業はプログラム ハンドルとして NULL を渡すことだけです。これにより、CBL_CANCEL_PROC ルーチンによって正しいプログラム ハンドルが自動的に特定され、正しいリストにエントリが作成されます。

通常、ローカル登録では、登録プログラムのエントリ ポイントを cblte-cppb-callback として指定します (必須ではありません)。

この方法は、たとえば、オペレーティング システムから直接割り当てられたリソースをプログラムのキャンセル前に割り当て解除する必要があるプログラムで使用されます。

サービス登録

これは少し複雑な登録方法で、サービス プログラム (つまり、他の COBOL プログラムに代わってリソースを管理するプログラム) でいずれかのクライアントがキャンセルされるときに通知を受け取る必要がある場合に使用されます。この登録方法の場合、CBL_GET_PROGRAM_INFO ルーチンの呼び出しを使用してプログラム ハンドルを取得する必要があります。CBL_PROGRAM_INFO へのパラメーターは、必要な機能によって異なります。最も一般的に使用されるのは、CBL_GET_PROGRAM_INFO ルーチンの function 2 を使用して呼び出し元プログラムのプログラム ハンドルを取得する方法です。

通常、サービス登録では、サービス プログラムのエントリ ポイントを cblte-cppb-callback として指定します (必須ではありません)。

この方法は、たとえば、他の複数の COBOL プログラムに代わってファイルを開いて管理するファイル ハンドラー モジュールで、いずれかのプログラムがキャンセルされるときに、そのプログラムの代わりに開かれたすべてのファイルを COBOL のセマンティクスに従って自動的に閉じる必要がある場合に使用されます。

この例の場合は、ファイルを開く各プログラムにローカル登録を含めて、それぞれのファイルを閉じることも可能です。ただし、そのような方法ではエラーが発生しやすく、COBOL のセマンティクスにも準拠しないため、非常に乱雑になります。

CBL_CANCEL_PROC ルーチンをサービス プログラムに使用する際は、該当するリソースがクライアント プログラムで使用されなくなったときに、そのリソースについての通知を対応するクライアント プログラムのキャンセル リストから削除することが重要です。これは function を 3 または 4 に設定することで行います。これを効率的に行うために、function が 0 または 1 に設定されたときに返されるプログラム ハンドルをサービス プログラムのリソース構造に格納することができます。これにより、function が 3 または 4 に設定されたときに登録ハンドルとして返すハンドルを簡単に特定できます。

サービス プログラムで function 3 または 4 を使用した登録解除に失敗した場合、クライアント プログラムが最終的にキャンセルされたときに不要な通知が発生し、予期しない結果になります。

キャンセル ルーチンで他のプログラムをキャンセルする場合、それらのプログラム自体に CBL_CANCEL_PROC が登録されていてはなりません。

CBL_CANCEL_PROC では、3 つの必須の情報 (function を 0 または 1 に設定して得られるプログラム ハンドル、cblte-cppb-callback、およびキャンセル優先度) に加え、4 つ目のオプションとして cblte-cppb-userdata も指定できます。

ユーザー データ領域

cblte-cppb-callback を登録するプログラムで cblte-cppb-userdata パラメーターを使用すると、プログラムがキャンセルされたことを通知するときに cblte-cppb-callback に渡すパラメーターを指定することができます。各登録に異なる cblte-cppb-userdata パラメーターを指定することも、複数の登録に対して同じ cblte-cppb-userdata フィールドを指定することもできます。さらに、cblte-cppb-userdata-length パラメーターにゼロ以外の値を指定することで、cblte-cppb-userdata パラメーターをコピーする (そのコピーを cblte-cppb-callback にパラメーターとして渡す) ように指定することもできます。

この機能は、サービス プログラムで使用すると非常に便利です。CBL_CANCEL_PROC 登録プロセスに cblte-cppb-userdata パラメーターとして「ハンドル」を渡しておけば、クライアント プログラムをサービス「ハンドル」に関連付けるためのリストをサービス プログラムで管理しなくても、cblte-cppb-callback へのパラメーターとしてサービス「ハンドル」を直接受け取ることができるからです。

cblte-cppb-userdata-length パラメーターをゼロ以外に設定

これは、ゼロに設定した cblte-cppb-userdata-length パラメーターを使用するよりも便利ですが(Windows 環境にのみ該当)、通常は cblte-cppb-userdata 領域が小さい場合にのみ使用します。cblte-cppb-userdata-length パラメーターをゼロ以外に設定すると、指定したバイト数が cblte-cppb-userdata パラメーターのアドレスからコピーされ、そのコピーがリストのエントリとして保持されます。関連するプログラム ハンドルに関連付けられたプログラムがキャンセルされると、cblte-cppb-userdata 領域のコピーが cblte-cppb-callback にパラメーターとして渡されます。このコピーは、cblte-cppb-callback から戻った後に COBOL ランタイム システムによって自動的に削除されます。

CBL_CANCEL_PROC ルーチンは、渡された cblte-cppb-userdata 領域の構造については認識せず、フラットなメモリ ブロックのみをコピーすることに注意してください。たとえば、ブロックに組み込まれた USAGE POINTER の項目はコピーされますが、それらが指すメモリはコピーされません。この場合、アプリケーション自体でデータ構造全体を割り当ててコピーし、そのコピーを cblte-cppb-userdata-length をゼロに設定して渡す方が通常は適切です。

.NET では、cblte-cppb-userdata-length をゼロに設定しないでください。

cblte-cppb-userdata-length パラメーターをゼロに設定

cblte-cppb-userdata-length パラメーターをゼロに設定すると、登録プロセスに対して指定された元の cblte-cppb-userdata パラメーターが cblte-cppb-callback に渡され、そのブロック内のすべてのデータ構造が cblte-cppb-callback で削除または割り当て解除されます。

この方法を使用して cblte-cppb-userdata パラメーターを渡す場合、特に同じ cblte-cppb-userdata 領域を複数の登録ハンドルに登録するときは注意が必要です (登録ハンドルは終了時に cblte-cppb-handle パラメーターで返されます)。具体的には、割り当てられたリソースの割り当て解除はいずれも 1 回だけとし、関連付けられた最後の登録ハンドルが破棄されるまでは割り当てられたリソースが有効なままになるように注意する必要があります。これは、通常、cblte-cppb-userdata 領域のどこかに usage-count フィールドを含め、cblte-cppb-userdata パラメーターが登録ハンドルに登録されるたびにカウントを増やし、それをパラメーターとして cblte-cppb-callback が呼び出されるたびにカウントを減らすように設定することで実現できます。

優先度 (function の値に 1 を使用して設定) は、ユーザー コードについては 0 から 127 までの範囲で指定する必要があります。優先度 200 から 209 までは、ファイル ハンドラー用に予約されています。他の優先度の値を指定すると予期しない結果になります。デフォルト値は 64 で、ほとんどのアプリケーションではデフォルトのままでかまいません。

CANCEL ルーチンの実装

本セクションでは、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 prog-id      usage pointer.
 01 cblte-cppb-userdata       usage pointer.

 procedure division.
 entry "user-cblte-cppb-callback" using by value cancel-reason
                             by value       cancel-flags
                             by value       prog-id
                             by value       cblte-cppb-userdata.
 cblte-cppb-callback section.
 cblte-cppb-callback-para.
*> This is where the code which handles the CANCEL-notification goes.
*> The cblte-cppb-userdata field specified in the registration is passed
*> to us here, along with the program-id of the program being canceled.
*> If this routine is handling registrations which specified a
*> cblte-cppb-userdata-field length of zero, then the memory pointed to
*> by cblte-cppb-userdata may also need to be freed before returning.

 exit program returning cancel-status.

cancel-reason パラメーターは CANCEL の理由を示します。次のように設定できます。

ビット 0 (値 1)	STOP RUN の処理による CANCEL。
ビット 6 (値 64)	DEINSTALL (function を 4 に設定した CBL_CANCEL_PROC の呼び出し) による CANCEL。

他のビットはすべて予約されており、設定しても無視されます。

cancel-flags パラメーターは現在予約されており、設定しても無視されます。