メッセージのキューからの取り出し

次は、TPDEQUEUE() の構文です。

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

この呼び出しが行われると、TPQUEDEF-REC 内の QSPACE-NAME で指定されたキュー・スペースの TPQUEDEF-REC の QNAME キューからメッセージを取り出すようにシステムが指示されます。メッセージは、DATA-REC に挿入されます。TPTYPE-REC の LEN にデータ長が設定されます。TPDEQUEUE() から返された LEN が 0 の場合、そのメッセージにはデータ部がないことを示します。TPQUEDEF-REC の設定によって、システムに TPDEQUEUE() 呼び出しの処理方法が通知されます。

TPDEQUEUE() の引数

TPDEQUEUE():TPQUEDEF-REC 引数内の QSPACE-NAME

QSPACE-NAME は、管理者によって既に作成されたキュー・スペースを識別します。TMQUEUE サーバがコンフィギュレーション・ファイルの SERVERS セクションで定義されている場合、そのサーバが提供するサービス名は、実際のキュー・スペース名 (GROUPS セクションの OPENINFO パラメータの一部として指定されます) のエイリアスになります。たとえば、アプリケーションがサーバ TMQUEUE を使用する場合、QSPACE-NAME 引数が指す値は、TMQUEUE が宣言するサービス名になります。サービスのエイリアスが何も定義されていない場合、デフォルトのサービス名は TMQUEUE サーバと同じエイリアスになります。その場合、コンフィギュレーション・ファイルには次の内容が記述されています。

TMQUEUE　
        SRVGRP = QUE1  SRVID = 1　
        GRACE = 0  RESTART = Y CONV = N　
        CLOPT = "-A"
または
        CLOPT = "-s TMQUEUE"　

サーバ・グループ QUE1 のエントリには、OPENINFO パラメータを使用して、リソース・マネージャ、デバイスのパス名、およびキュー・スペース名を指定します。クライアント・プログラムにおける QSPACE-NAME 引数は、次のように記述されます。

  01 TPQUEDEF-REC.　
     COPY TPQUEDEF.　
  01 TPTYPE-REC.　
     COPY TPTYPE.　
  01 TPSTATUS-REC.　
     COPY TPSTATUS.　
  01 USER-DATA-REC  PIC X(100).　
*　
*　
*　
  MOVE LOW-VALUES TO TPQUEDEF-REC.　
  MOVE "TMQUEUE" TO QSPACE-NAME IN TPQUEDEF-REC.　
  MOVE "REPLYQ" TO QNAME IN TPQUEDEF-REC.　
  SET TPTRAN IN TPQUEDEF-REC TO TRUE.　
  SET TPBLOCK IN TPQUEDEF-REC TO TRUE.　
  SET TPTIME IN TPQUEDEF-REC TO TRUE.　
  SET TPSIGRSTRT IN TPQUEDEF-REC TO TRUE.　
  MOVE LOW-VALUES TO TPTYPE-REC.　
  MOVE "STRING" TO REC-TYPE IN TPTYPE-REC.　
  MOVE LENGTH OF USER-DATA-REC TO LEN IN TPTYPE-REC.　
  CALL "TPDEQUEUE" USING　
          TPQUEDEF-REC　
          TPTYPE-REC　
          USER-DATA-REC　
          TPSTATUS-REC.

TPDEQUEUE():TPQUEDEF-REC 引数内の QNAME

キュー・スペース内のキュー名は、そのキュー・スペースにアクセスするアプリケーション間で一貫していなければなりません。これは、応答キューでは特に重要です。QNAME が応答キューを参照する場合、管理者はほかのキューと同じ方法で応答キュー、そして多くの場合、エラー・キューも作成します。QNAME には、メッセージまたは応答を取り出すキューの名前が指定されています。

TPDEQUEUE():DATA-REC および TPTYPE-REC 引数内の LEN

この引数は、TPENQUEUE() で使用される場合と若干意味が異なります。DATA-REC は、キューから取り出されたメッセージをシステムが格納する場所を示します。

入力として LEN に 0 が設定されている場合はエラーになります。TPDEQUEUE() が戻ると、LEN には取り出されたデータの長さが格納されます。0 は応答にデータがなかったことを示します。アプリケーションによっては、これは正当で正常な応答です。長さ 0 の応答を受信した場合でも、それをキューに登録された要求の正常処理を示すために使用できます。レコードが TPDEQUEUE() 呼び出しの前と比べて変更されているかどうかを確認する場合は、TPDEQUEUE() 呼び出しの前にデータ長を保存し、それを呼び出しが終了した後で LEN と比較します。応答が LEN より長い場合、DATA-REC にはこのレコードに格納できるだけのバイト数が挿入されます。それを超える部分は破棄され、TPTRUNCATE が設定されて TPDEQUEUE() は失敗します。

TPDEQUEUE():TPQUEDEF-REC の設定値

TPQUEDEF-REC の設定値は、TPDEQUEUE() 呼び出しの処理方法を BEA Tuxedoシステムに通知するために使用されます。次は、有効な設定です。

TPQUEDEF-REC 構造体

TPDEQUEUE() への入力では、次のフィールドを TPQUEDEF 構造体に設定します。

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。

TPQWAIT の使用

フラグに TPQWAIT を設定して TPDEQUEUE() を呼び出すと、メッセージをすぐに取り出すことができない場合、TPDEQUEUE() が制御を呼び出し元に返す前に、TMQUEUE サーバは TPDEQUEUE() 要求に一致するメッセージがキューに到着するのを待ちます。TMQUEUE プロセスは待機中の要求を無視し、ほかのプロセスの要求を処理しながら、最初の要求の条件が満たされるのを待ちます。TPQGETBYMSGID や TPQGETBYCORRID も指定されている場合、サーバは指定されたメッセージ識別子や相関識別子を持つメッセージをキューから取り出せるようになるまで待ちます。このどちらのフラグも設定されていない場合、サーバは任意のメッセージがキューに登録されるまで待ちます。呼び出しがトランザクション・モードの場合、サーバの待機時間は、呼び出し元のトランザクション・タイムアウトによって制御されます。呼び出しがトランザクション・モードでない場合、TMQUEUE サーバの CLOPT パラメータに指定される -t オプションで制御されます。

TMQUEUE サーバは、要求を処理するアクション・リソースを利用できる限り、複数の待機中 TPDEQUEUE() 要求を同時に処理できます。十分なアクション・リソースがキュー・スペースに対して設定されていない場合、TPDEQUEUE() は失敗します。使用しているシステムがこれに該当する場合は、キュー・スペースに対するアクション・リソースの数を増やしてください。

TMQFORWARD サービス使用時のエラー処理

キューからのメッセージの取り出しで、エラー処理の最良の方法を考慮する場合、次の 2 種類のエラーを区別しておきます。

デフォルトでは、メッセージがトランザクション内でキューから取り出され、そのトランザクションがロールバックされると、そのメッセージはキューに戻されて、再度キューからの取り出しと実行が可能になります。一時的な障害が解消されるように (たとえば、データベースのロックを別のトランザクションが解除するように) 少し時間をおいてから、メッセージの取り出しと実行を再度試みます。通常、再試行の回数に上限を設定することも、アプリケーション不備によってリソースを著しく浪費することを防ぐために有用です。管理者がキューを設定するときに、再試行の回数と遅延時間 (秒単位) の両方を指定できます。再試行の回数 0 は、再試行が行われないことを示します。再試行の回数が上限に達すると、管理者がキュー・スペースに設定するエラー・キューにメッセージが移動されます。エラー・キューが設定されていない場合、再試行回数の上限に達したメッセージは単に削除されます。エラー・キューにあるメッセージは、管理者によって処理されなければなりません。管理者は、アプリケーションの要件を満たす方法で発信元に通知する必要があります。選択されたメッセージ処理方法は、メッセージをキューに登録した発信元プログラムにほとんど透過的です。メッセージは一度正常にキューに登録されると、TPENQUEUE() のパラメータおよびキューの属性に従って処理されることが実質的には保証されます。メッセージがエラー・キューに移動されたことの通知は、キューのパラメータを適切に調整されたシステムではほとんどありません。

異常終了キュー (通常、キュー・スペースのエラー・キューとは異なります) は、キューに登録された各メッセージと対応付けられます。このキューは、異常終了メッセージを置く場所として、キューにメッセージを登録する呼び出しで指定されます。特定の要求に対する異常終了メッセージは、アプリケーション生成の相関識別子で識別できます。相関識別子は、キューにメッセージを登録するときに、そのメッセージと対応付けられます。

成功するまで (または事前に定義された回数まで) 再試行を繰り返すというデフォルトの動作は、時間が経過すれば解決されるような一時的な障害が失敗の原因であり、メッセージが後から適切に処理される場合は適しています。

障害が一時的なものではない場合もあります。たとえば、存在しないアカウントでの操作を要求するメッセージがキューに入れられている場合 (アプリケーションも適当な時間に存在していない場合) です。その場合、再試行してリソースを浪費しないようにします。アプリケーション・プログラマまたは管理者が、特定の操作の失敗が一時的ではないと判断した場合、単に再試行回数を 0 に設定します。ただし、この場合、このようなメッセージが入るキュー・スペースのエラー・キューを継続的にクリアするメカニズム (キューを定期的に読み取るバックグラウンドのクライアントなど) が必要です。また、同じサービスに対する障害でも、一時的なもの (データベース・ロックの競合など) であったり、永続的なもの (アカウントが存在しないなど) であったりする場合が多くあります。

メッセージが TMQFORWARD によって処理される (キューから取り出され、TPCALL を介してアプリケーションに渡される) 場合、TPCALL が返す情報には、TPESVCFAIL エラーが一時的な障害と永続的な障害のどちらによって生じたものであるかを示すメカニズムはありません。

キューからの取り出しをアプリケーションが処理する場合、簡単な解決方法はたとえ操作が失敗しても、そのサービスに対して成功を返すことです。つまり、TPSUCCESS を設定して TPRETURN を実行します。これにより、トランザクションはコミット可能になり、メッセージはキューから削除されます。応答メッセージが使用されている場合、サービスから返されるバッファの情報によって操作の失敗を示すことができ、メッセージが応答キューに登録されます。TPRETURN の TPSVCRET-REC 引数内の APPL-CODE も、アプリケーション固有の情報を返すために使用できます。

サービスが失敗し、トランザクションをロールバックする必要がある場合、TMQFORWARD が処理をそれ以上行わずに、2 番目のトランザクションを実行してキューからメッセージを削除するかどうかは明確ではありません。デフォルトでは、TMQFORWARD は失敗したサービスに対するメッセージを削除しません。TMQFORWARD のトランザクションはロールバックされ、メッセージはキューに格納されます。TMQFORWARD にコマンド行オプションを指定すると、サービスが失敗して 0 より長い応答メッセージが返された場合に、メッセージがキューから削除されます。メッセージは、2 番目のトランザクションで削除されます。この処理を行うには、キューに遅延時間および再試行回数を設定する必要があります。メッセージが異常終了キューに対応付けられている場合、メッセージがキューから削除されたトランザクションと同じトランザクションで、応答データが異常終了キューに登録されます。

TMQFORWARD を通して呼び出されたサービスからの応答をキューから取り出す手順

アプリケーションがキューに登録されたメッセージに対する応答を要求している場合、次の手順に従います。