TPDEQUEUE(3cbl)

名前

TPDEQUEUE() - キューからメッセージを取り出すルーチン

形式

01 TPQUEDEF-REC.
 COPY TPQUEDEF. 
 
01 TPTYPE-REC.
 COPY TPTYPE. 
 
01 DATA-REC.
 COPY User data. 
 
01 TPSTATUS-REC.
 COPY STATDEF. 
 
CALL "TPDEQUEUE" USING TPQUEDEF-REC TPTYPE-REC DATA-REC TPSTATUS-REC.

機能説明

TPDEQUEUE() は、キュー・スペース QSPACE-NAME 内の QNAME で指定されるキューから、処理するメッセージを取り出します。

省略時設定では、キューの先頭のメッセージが取り出されます。 キュー上のメッセージの順序は、そのキューの作成時に定義されます。 アプリケーションは、MSGID を使用してメッセージ識別子を指定するか、または CORRID を使用して相関識別子を指定することにより、特定のメッセージをキューから取り出すことを要求できます。 メッセージを現在取り出せない場合には、アプリケーションはメッセージを待つことを示すために、TPQUEDEF-REC 設定を使用することもできます。 また、TPQUEDEF-REC 構造体を使用して、メッセージを読み出してもそれがキューから削除されないようにしたり、キュー上の相対位置が変更されないようにすることが可能です。 この後のこのレコードについての説明を参照してください。.

DATA-REC は、キューから取り出されたメッセージの読み込み先を指定します。入力時の LEN は、DATA-REC へ移動する最大バイト数を示します。 正常終了時には、LEN には、DATA-REC へ移動された実際のバイト数が入ります。 REC-TYPE および SUB-TYPE には、それぞれ応答のタイプおよびサブタイプが入ります。 応答が DATA-REC より大きい場合は、DATA-REC にはこのレコードに入るバイト数分のみが入ります。応答の残りは破棄され、TPDEQUEUE() は異常終了して [TPTRUNCATE] を返します。

正常終了時に LEN が 0 である場合は、応答にはデータ部がなく、DATA-REC は変更されていません。 入力時に LEN を 0 にすると、エラーになります。

呼び出し元がトランザクション・モードにあり、TPTRAN が設定されている場合は、メッセージは、トランザクション・モードでキューから取り出されます。 この結果、TPDEQUEUE が正常終了して呼び出し元のトランザクションが正常にコミットされると、メッセージはキューから削除されます。 呼び出し元のトランザクションが、明示的に、またはトランザクション・タイムアウトあるいはなんらかの通信エラーの結果としてロールバックされると、メッセージはキュー上に残されます。つまり、キューからのメッセージの削除もロールバックされます。 同じトランザクション内で、同じメッセージの登録と取り出しを行うことはできません。

呼び出し元がトランザクション・モードにないか、または TPNOTRAN が設定されている場合は、メッセージはトランザクション・モードではキューから取り出されません。 トランザクション・モードでない場合に通信エラーまたはタイムアウトが発生すると、アプリケーションには、メッセージが正しくキューから取り出されたかどうかがわからず、メッセージが失われることがあります。

次に、TPQUEDEF-REC の有効な設定の一覧を示します。

TPDEQUEUE() が正常終了すると、アプリケーションは TPQUEDEF-REC を使用してメッセージに関する追加情報を取得できます。 この情報には、キューから取り出されたメッセージのメッセージ識別子、すべての応答または異常終了メッセージに付随し発信元がメッセージと元の要求を結び付けることができるようにする相関識別子、メッセージに対する配信サービスの品質、メッセージの応答に対する配信サービスの品質、応答が要求された場合は応答キューの名前、およびメッセージをキューから取り出すときの失敗に関する情報をアプリケーションが登録できる異常終了キューの名前が含まれます。 これらについて以下に説明します。

制御構造体

TPQUEDEF-REC は、アプリケーション・プログラムが、キューからのメッセージの取り出しに関連する情報を渡したり、取得したりするために使用します。 TPQUEDEF-REC の設定は、構造体の他のどの要素が有効であるかを示すために使用されます。

TPDEQUEUE() への入力時には、次の要素を TPQUEDEF-REC に設定できます。

05 MSGID    PIC X(32).
05 CORRID   PIC X(32).

TPDEQUEUE() の入力情報を制御する TPQUEDEF-REC の有効な設定の一覧を次に示します。

TPDEQUEUE() からの出力時には、次の要素が TPQUEDEF-REC に設定されます。

05 PRIORITY                PIC S9(9) COMP-5. 
05 MSGID                   PIC X(32). 
05 CORRID                  PIC X(32). 
05 TPQUEQOS-DELIVERY-FLAG  PIC S9(9) COMP-5. 
05 TPQUEQOS-REPLY-FLAG     PIC S9(9) COMP-5. 
05 REPLYQUEUE              PIC X(15). 
05 FAILUREQUEUE            PIC X(15). 
05 DIAGNOSTIC              PIC S9(9) COMP-5. 
05 CLIENTID OCCURS 4 TIMES PIC S9(9) COMP-5 
05 APPL-RETURN-CODE        PIC S9(9) COMP-5. 
05 APPKEY                  PIC S9(9) COMP-5.

TPDEQUEUE() からの出力情報を制御する TPQUEDEF-REC の有効な設定を次に示します。 どの設定でも、TPDEQUEUE() の呼び出し時に真の場合、メッセージがキューに入れられたときに提供された値が、レコード内の対応する要素に格納され、その設定は真のままになります。 値を利用できない、つまりメッセージがキューに入れられたときに値が提供されていない場合、または TPDEQUEUE()の呼び出し時に設定が真でない場合、その設定が真でない状態で TPDEQUEUE() は完了します。

TPQUEDEF-REC の残りの設定は、TPDEQUEUE() が呼び出されると、次の値に設定されます。 TPQNOTOP、TPQNOBEFOREMSGID、TPQNOTIME_ABS、TPQNOTIME_REL、TPQNOEXPTIME_ABS、TPQNOEXPTIME_REL、および TPQNOEXPTIME_NONE。

TPDEQUEUE() の呼び出しが異常終了し、TP-STATUS に TPEDIAGNOSTIC が設定された場合は、異常終了の原因を示す値が DIAGNOSTIC に返されます。 返される可能性のある値は、この後の「診断」の項で定義しています。

また、TPDEQUEUE() 呼び出しが正常終了した場合の出力時には、APPKEY にアプリケーション認証キーが設定され、CLIENTID に要求の発信元であるクライアントの識別子が設定され、APPL-RETURN-CODE にメッセージ登録時に設定されたユーザ戻りコードが設定されます。

戻り値

TPDEQUEUE() は正常終了時には、TP-STATUS に [TPOK] を設定します。

エラー

次の条件が発生すると、TPDEQUEUE() は異常終了し、TP-STATUS に次の値を設定します。特に説明がなければ、この障害は呼び出し元のトランザクションには影響しません。

診断

次の診断値は、キューからのメッセージの取り出し中に返されます。

関連項目