Tuxedo /Q コンポーネント

     前  次    新しいウィンドウで目次を開く     
ここから内容の開始

Oracle Tuxedo/Q COBOL 言語プログラミング

ここでは、以下の内容について説明します。

 

はじめに

ここでは、キューへのメッセージの登録とキューからのメッセージの取り出しを行う ATMI COBOL 言語関数 TPENQUEUE(3cbl)、TPDEQUEUE(3cbl)、およびいくつかの補助関数の使用方法について説明します。

 

必要とされる知識

キュー機能を使用するクライアント プログラムまたはサーバ プログラムをコーディングする Oracle TUXEDO プログラマには、Oracle Tuxedo ATMI にバインドされた COBOL 言語についての知識が必要です。Oracle Tuxedo プログラミングに関する全般的な説明については、『COBOL を使用した Oracle Tuxedo アプリケーションのプログラミング』を参照してください。ATMI 関数の詳細については、『Tuxedo COBOL リファレンス』を参照してください。

 

要求の発信元

Oracle Tuxedo /Q のキューにメッセージを登録する呼び出しは、アプリケーションに対応付けられているあらゆるクライアント プロセスまたはサーバ プロセスから行うことができます。たとえば、次の発信元があります。

 

デフォルトの場合の注意事項

ここでは、Oracle Tuxedo /Q プログラミングについて、図「キュー サービスの呼び出し」の主にクライアント部分について説明します。この図では、クライアント (または、クライアントとして機能するプロセス) は TPENQUEUE(3cbl) を呼び出し、TMQUEUE(5) サーバを通して利用できるキュー スペースを指定して、メッセージをキューに登録しています。クライアントは、その後、TMQUEUE への TPDEQUEUE(3cbl) 呼び出しを介して、応答を取得します。

図では、キューに入れられたメッセージが、サーバ TMQFORWARD(5) によってキューから取り出され、処理のために TPCALL(3cbl) を介してアプリケーション サーバに送信されています。TPCALL に対する応答が受信されると、TMQFORWARD は応答メッセージをキューに登録します。TMQFORWARD は、キュー スペースと既存のアプリケーション サービスとの間にインタフェースを提供するので、アプリケーションにコードを追加する必要はありません。そのため、ここでは、クライアントとキュー スペースとの間の処理を中心に説明します。

基本的なモデルについて説明し、その後でカスタマイズの例をいくつか示します。

 

メッセージのキューへの登録

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

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

TPENQUEUE() が呼び出されると、TPQUEDEF-REC 内の QSPACE-NAME で識別されるキュー スペース内の TPQUEDEF-REC の QNAME キューにメッセージを格納するようにシステムに指示します。メッセージは DATA-REC にあり、TPTYPE-REC 内の LEN にはメッセージの長さが入ります。TPQUEDEF-REC の設定によって、システムに TPENQUEUE() 呼び出しの処理方法が通知されます。キューに登録されるメッセージ、および応答の処理方法についてのさらに詳しい情報は、TPQUEDEF-REC 構造体で定義されます。

TPENQUEUE() の引数

TPENQUEUE(3cbl) の処理を制御するいくつかの重要な引数があります。その一部について、以下に説明します。

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

QSPACE-NAME は、管理者によって既に作成されたキュー スペースを識別します。サーバがコンフィグレーション ファイルの 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 "STRING" 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 "TPENQUEUE" USING
         TPQUEDEF-REC
         TPTYPE-REC
         USER-DATA-REC
         TPSTATUS-REC.

TMQUEUE(5) リファレンス ページの例では、サーバを作成してコンフィグレーション ファイルで指定する際に、サービスのエリアスを指定する方法が示されています。「サンプル アプリケーション」のサンプル プログラムでも、サービスのエリアスが指定されています。

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

キュー スペースで、メッセージ キューを使用してサービスが呼び出されている場合、メッセージ キューは、要求の処理に利用できるアプリケーション サービスに従って名前が付けられます。QNAME には、そのような値が含まれます。QNAME がアプリケーション サービスではない場合の例外については、「TMQFORWARD を通して呼び出されたサービスからの応答をキューから取り出す手順」で説明します。

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

DATA-REC には、処理対象のメッセージが入ります。TPTYPE-REC 内の LEN は、メッセージの長さを指定します。Oracle Tuxedo のレコード タイプには、LEN を指定する必要がないもの (VIEW など) もあります。その場合、引数は無視されます。TPTYPE-REC 内の RECTYPE が SPACES の場合、DATA-REC および LEN は無視され、メッセージはデータ部なしでキューに登録されます。

TPENQUEUE(): TPQUEDEF-REC の設定値

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

TPNOTRAN

呼び出し側がトランザクション モードにあり、この設定が使用されていると、メッセージは呼び出し側と同じトランザクション内ではキューに登録されません。この値が設定されたトランザクション モードの呼び出し側には、トランザクション タイムアウトが適用されます。それ以外は適用されません。この設定を使用した状態で呼び出されたキューへのメッセージの登録が失敗した場合、呼び出し側のトランザクションは影響されません。TPNOTRAN または TPTRAN のいずれかを設定しなければなりません。

TPTRAN

呼び出し側がトランザクション モードにある場合、この設定はキューへのメッセージの登録が同じトランザクション内で行われることを指定します。TPNOTRAN または TPTRAN のいずれかを設定しなければなりません。

TPNOBLOCK

ブロッキング状態が存在する場合、メッセージはキューに登録されません。TPNOBLOCK が設定されている場合に、メッセージの転送先である内部バッファがいっぱいであるなどのブロッキング状態が存在すると、呼び出しは失敗し、tperrno(5) に TPEBLOCK が設定されます。TPNOBLOCK が設定されている場合に、ターゲットのキューが別のアプリケーションによって排他的にオープンされているというブロッキング状態が存在すると、呼び出しは失敗し、tperrno() に TPEDIAGNOSTIC が設定され、TPQCTL 構造体の診断フィールドに QMESHARE が設定されます。後者の場合、Oracle Tuxedo システム以外の Oracle Products に基づくほかのアプリケーションが、キューイング サービス API (QSAPI) を使用して読み取りと書き込み、またはそのいずれかを排他的に行うためにキューをオープンしています。TPNOBLOCK または TPBLOCK のいずれかを設定しなければなりません。

TPBLOCK

TPBLOCK が設定されている場合に、ブロッキング状態が存在すると、その状態が解消されるかタイムアウト (トランザクション タイムアウトまたはブロッキング タイムアウト) が発生するまで、呼び出し側はブロックされます。TPNOBLOCK または TPBLOCK のいずれかを設定しなければなりません。

TPNOTIME

この設定は、呼び出しにブロッキング タイムアウトが適用されないことを示します。ただし、トランザクション タイムアウトは発生する可能性があります。TPNOTIME または TPTIME のいずれかを設定しなければなりません。

TPTIME

この設定は、呼び出しにブロッキング タイムアウトが適用されることを示します。TPNOTIME または TPTIME のいずれかを設定しなければなりません。

TPSIGRSTRT

この設定は、基となるシステム コールがシグナルによって中断された場合、中断されたシステム コールが再度呼び出されることを指定します。TPSIGRSTRT または TPNOSIGRSTRT のいずれかを設定しなければなりません。

TPNOSIGRSTRT

この設定は、基となるシステム コールがシグナルによって中断された場合、中断されたシステム コールが再度呼び出されないことを指定します。呼び出しは失敗し、TP-STATUS に TPEGOTSIG が設定されます。TPSIGRSTRT または TPNOSIGRSTRT のいずれかを設定しなければなりません。

TPQUEDEF-REC 構造体

TPQUEDEF-REC 構造体には、アプリケーションで使用されるメンバーと Oracle Tuxedo システムで使用されるメンバーがあり、アプリケーション プログラムとキュー機能間の両方向でパラメータがやり取りされます。この構造体は、COBOL COPY ファイル内で定義されています。TPQUEDEF-REC を呼び出すクライアントは、設定値を使用して、システム側で入力する必要のあるフィールドをマークします。この構造体は、TPDEQUEUE() でも使用されます。一部のメンバーは、アプリケーションが TPDEQUEUE() を呼び出すまで使用されません。次のコード例は、この構造体全体を示しています。

コード リスト 4-1 TPQUEDEF-REC 構造体 
        05 TPBLOCK-FLAG         PIC S9(9) COMP-5.
                88 TPBLOCK              VALUE 0.
                88 TPNOBLOCK            VALUE 1.
        05 TPTRAN-FLAG  PIC S9(9) COMP-5.
                88 TPTRAN               VALUE 0.
                88 TPNOTRAN             VALUE 1.
        05 TPTIME-FLAG  PIC S9(9) COMP-5.
                88 TPTIME               VALUE 0.
                88 TPNOTIME             VALUE 1.
        05 TPSIGRSTRT-FLAG      PIC S9(9) COMP-5.
                88 TPNOSIGRSTRT         VALUE 0.
                88 TPSIGRSTRT           VALUE 1.
        05 TPNOCHANGE-FLAG      PIC S9(9) COMP-5.
                88 TPCHANGE             VALUE 0.
                88 TPNOCHANGE           VALUE 1.
        05 TPQUE-ORDER-FLAG     PIC S9(9) COMP-5.
                88 TPQDEFAULT           VALUE 0.
                88 TPQTOP               VALUE 1.
                88 TPQBEFOREMSGID       VALUE 2.
        05 TPQUE-TIME-FLAG      PIC S9(9) COMP-5.
                88 TPQNOTIME            VALUE 0.
                88 TPQTIME-ABS          VALUE 1.
                88 TPQTIME-REL          VALUE 2.
        05 TPQUE-PRIORITY-FLAG  PIC S9(9) COMP-5.
                88 TPQNOPRIORITY        VALUE 0.
                88 TPQPRIORITY          VALUE 1.
        05 TPQUE-CORRID-FLAG    PIC S9(9) COMP-5.
                88 TPQNOCORRID          VALUE 0.
                88 TPQCORRID            VALUE 1.
        05 TPQUE-REPLYQ-FLAG    PIC S9(9) COMP-5.
                88 TPQNOREPLYQ          VALUE 0.
                88 TPQREPLYQ            VALUE 1.
        05 TPQUE-FAILQ-FLAG     PIC S9(9) COMP-5.
                88 TPQNOFAILUREQ        VALUE 0.
                88 TPQFAILUREQ          VALUE 1.
        05 TPQUE-MSGID-FLAG     PIC S9(9) COMP-5.
                88 TPQNOMSGID           VALUE 0.
                88 TPQMSGID             VALUE 1.
        05 TPQUE-GETBY-FLAG     PIC S9(9) COMP-5.
                88 TPQGETNEXT           VALUE 0.
                88 TPQGETBYMSGIDOLD     VALUE 1.
                88 TPQGETBYCORRIDOLD    VALUE 2.
                88 TPQGETBYMSGID        VALUE 3.
                88 TPQGETBYCORRID       VALUE 4.
        05 TPQUE-WAIT-FLAG      PIC S9(9) COMP-5.
                88 TPQNOWAIT            VALUE 0.
                88 TPQWAIT              VALUE 1.
        05 TPQUE-DELIVERY-FLAG  PIC S9(9) COMP-5.
                88 TPQNODELIVERYQOS     VALUE 0.
                88 TPQDELIVERYQOS       VALUE 1.
        05 TPQUEQOS-DELIVERY-FLAG       PIC S9(9) COMP-5.
                88 TPQQOSDELIVERYDEFAULTPERSIST VALUE 0.
                88 TPQQOSDELIVERYPERSISTENT     VALUE 1.
                88 TPQQOSDELIVERYNONPERSISTENT  VALUE 2.
        05 TPQUE-REPLY-FLAG     PIC S9(9) COMP-5.
                88 TPQNOREPLYQOS                VALUE 0.
                88 TPQREPLYQOS                  VALUE 1.
        05 TPQUEQOS-REPLY-FLAG  PIC S9(9) COMP-5.
                88 TPQQOSREPLYDEFAULTPERSIST    VALUE 0.
                88 TPQQOSREPLYPERSISTENT        VALUE 1.
                88 TPQQOSREPLYNONPERSISTENT     VALUE 2.
        05 TPQUE-EXPTIME-FLAG   PIC S9(9) COMP-5.
                88 TPQNOEXPTIME         VALUE 0.
                88 TPQEXPTIME-ABS       VALUE 1.
                88 TPQEXPTIME-REL       VALUE 2.
                88 TPQEXPTIME-NONE      VALUE 3.
        05 TPQUE-PEEK-FLAG      PIC S9(9) COMP-5.
                88 TPQNOPEEK            VALUE 0.
                88 TPQPEEK              VALUE 1.
        05 DIAGNOSTIC           PIC S9(9) COMP-5.
                88 QMEINVAL             VALUE -1.
                88 QMEBADRMID           VALUE -2.
                88 QMENOTOPEN           VALUE -3.
                88 QMETRAN              VALUE -4.
                88 QMEBADMSGID          VALUE -5.
                88 QMESYSTEM            VALUE -6.
                88 QMEOS                VALUE -7.
                88 QMEABORTED           VALUE -8.
                88 QMEPROTO             VALUE -9.
                88 QMEBADQUEUE          VALUE -10.
                88 QMENOMSG             VALUE -11.
                88 QMEINUSE             VALUE -12.
                88 QMENOSPACE           VALUE -13.
                88 QMERELEASE           VALUE -14.
                88 QMEINVHANDLE         VALUE -15.
                88 QMESHARE             VALUE -16.
        05 DEQ-TIME             PIC 9(9) COMP-5.
        05 EXP-TIME             PIC 9(9) COMP-5.
        05 PRIORITY             PIC S9(9) COMP-5.
        05 MSGID                PIC X(32).
        05 CORRID               PIC X(32).
        05 QNAME                PIC X(15).
        05 QSPACE-NAME          PIC X(15).
        05 REPLYQUEUE           PIC X(15).
        05 FAILUREQUEUE         PIC X(15).
        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.

次は、TPENQUEUE の入力情報を制御するパラメータの有効な設定です。

TPQTOP

この値を設定すると、キューの順序付けは無効になり、メッセージはキューの先頭に登録されます。この要求は、順序付けを無効にするようにキューが設定されているかどうかによって、使用できない場合があります。デフォルトのキューの順序を使用する場合は、TPQDEFAULT を設定します。TPQTOP、TPQBEFOREMSGID、TPQDEFAULT のいずれかを設定しなければなりません。

TPQBEFOREMSGID

この値を設定すると、キューの順序付けが無効になり、メッセージは MSGID によって識別されるメッセージの前に登録されます。この要求は、順序付けを無効にするようにキューが設定されているかどうかによって、使用できない場合があります。デフォルトのキューの順序を使用する場合は、TPQDEFAULT を設定します。TPQTOP、TPQBEFOREMSGID、TPQDEFAULT のいずれかを設定しなければなりません。
メッセージ識別子の値は 32 バイト全体が意味を持つので、MSGID で識別される値は、たとえば空白を埋め込むなどして、完全に初期化する必要があります。

TPQTIME-ABS

この値が設定されていると、DEQ-TIME で指定された時間の経過後、メッセージが処理されます。DEQ-TIME は、time(2) または mktime(3C) によって生成された絶対時間値、つまり世界協定時 (UTC) 1970 年 1 月 1 日 00:00:00 から経過した秒数を示します。絶対時間値も相対時間値も設定されていない場合は、TPQNOTIME を設定します。TPQTIME-ABS、TPQTIME-REL、TPQNOTIME のいずれかを設定しなければなりません。絶対時間は、キュー マネージャ プロセスが存在するマシン クロックによって決定されます。

TPQTIME-REL

この値が設定されていると、キューへの登録が完了してからの相対時間の経過後にメッセージが処理されます。DEQ-TIME は、キューへの登録が完了した後、送信されたメッセージが処理されるまでの遅延秒数を指定します。絶対時間値も相対時間値も設定されていない場合は、TPQNOTIME を設定します。TPQTIME-ABS、TPQTIME-REL、TPQNOTIME のいずれかを設定しなければなりません。

TPQPRIORITY

この値が設定されていると、メッセージがキューに登録されるときの優先順位が PRIORITY に格納されます。優先順位は、1 以上 100 以下の範囲でなければなりません。数値が高いほど優先順位も高くなり、高い数値のメッセージが低い数値のメッセージより先にキューから取り出されます。優先順位によって順序付けられていないキューでは、この値は参考として使用されます。TPQNOPRIORITY が設定されている場合、デフォルトでメッセージの優先順位が 50 になります。

TPQCORRID

この値を設定すると、メッセージが TPDEQUEUE() によってキューから取り出されるとき、CORRID に指定された相関識別子の値を使用することができます。この識別子は、キューに登録されたすべての応答メッセージまたは異常終了メッセージに付加されるので、アプリケーションは応答を特定の要求に結び付けることができます。相関識別子を使用できない場合は、TPQNOCORRID を設定します。
相関識別子の値は 32 バイト全体が意味を持つので、CORRID に指定される値は、たとえば空白を埋め込むなどして、完全に初期化する必要があります。

TPQREPLYQ

この値が設定されていると、REPLYQUEUE に指定された応答キューが、キューに入れられたメッセージに対応付けられます。メッセージへの応答はすべて、要求メッセージと同じキュー スペース内の、指定されたキューに登録されます。応答キューの名前を使用できない場合は、TPQNOREPLYQ を設定します。

TPQFAILUREQ

この値が設定されていると、FAILUREQUEUE に指定された異常終了キューが、キューに入れられたメッセージに対応付けられます。(1) キューに登録されたメッセージが TMQFORWARD() によって処理され、(2) TMQFORWARD が -d オプションで開始され、さらに (3) サービスが異常終了して NULL 以外の応答を返す場合は、その応答と関連する tpurcode によって構成される異常終了メッセージが、元の要求メッセージと同じキュー スペース内で指定されたキューに登録されます。異常終了キューの名前を使用できない場合は、TPQNOFAILUREQ を設定します。

TPQDELIVERYQOS
TPQREPLYQOS

TPQDELIVERYQOS が設定されていると、TPQUEQOS-DELIVERY-FLAG で指定されたフラグが、メッセージの配信に対するサービスの品質を制御します。相互に排他的な次のフラグ、TPQQOSDELIVERYDEFAULTPERSIST、TPQQOSDELIVERYPERSISTENT、または TPQQOSDELIVERYNONPERSISTENT のいずれかを設定する必要があります。TPQDELIVERYQOS が設定されていない場合は、TPQNODELIVERYQOS を設定する必要があります。TPQNODELIVERYQOS が設定されている場合、ターゲットのキューのデフォルトの配信ポリシーがメッセージに対するサービスの配信品質を指定します。
TPQREPLYQOS が設定されていると、TPQUEQOS-REPLY-FLAG で指定されるフラグが、応答メッセージの配信に対するサービスの品質を制御します。相互に排他的な次のフラグ、TPQQOSREPLYDEFAULTPERSIST、TPQQOSREPLYPERSISTENT、または TPQQOSREPLYNONPERSISTENT のいずれかを設定する必要があります。TPQREPLYQOS フラグは、TMQFORWARD によって処理されるメッセージから応答が返されるときに使用されます。サービスを呼び出すときに TMQFORWARD を使用しないアプリケーションでは、自身の応答メカニズムのヒントとして TPQREPLYQOS フラグを使用できます。 TPQREPLYQOS が設定されていない場合は、TPQNOREPLYQOS を設定する必要があります。TPQNOREPLYQOS が設定されている場合、REPLYQUEUE キューのデフォルトの配信ポリシーが応答に対するサービスの配信品質を指定します。デフォルトの配信方針は、メッセージに対する応答がキューに登録されるときに決定される点に注意してください。つまり、元のメッセージがキューに登録されてから応答が登録されるまでの間に、応答キューのデフォルトの配信方針が変更された場合、応答が最後に登録される時点で有効な方針が使用されます。 次は、有効な TPQUEQOS-DELIVERY-FLAG および TPQUEQOS-REPLY-FLAG のフラグです。

TPQQOSDELIVERYDEFAULTPERSIST
TPQQOSREPLYDEFAULTPERSIST

このフラグは、ターゲットまたは応答のキューで指定されているデフォルトの配信方針を使用して、メッセージが配信されるように指定します。

TPQQOSDELIVERYPERSISTENT
TPQQOSREPLYPERSISTENT

このフラグは、メッセージがディスク ベースの配信方法を使用して、永続的な記憶域に配信されることを指定します。このフラグが設定されていると、ターゲットまたは応答のキューに指定されたデフォルトの配信方針がこのフラグで上書きされます。

TPQQOSDELIVERYNONPERSISTENT
TPQQOSREPLYNONPERSISTENT

このフラグは、メッセージがメモリ ベースの配信方法を使用して、非永続的な記憶域に配信されることを指定します。メッセージは、キューから取り出されるまでメモリに登録されたままになります。このフラグが設定されていると、ターゲットまたは応答のキューに指定されたデフォルトの配信方針がこのフラグで上書きされます。
呼び出し側がトランザクション モードの場合、一時的メッセージは呼び出し側のトランザクション内でキューに登録されます。ただし、システムがシャットダウンしたりクラッシュしたりした場合、またはキュー スペースとしての IPC 共用メモリが除去された場合は、一時的メッセージは失われます。

TPQEXPTIME-ABS

この値が設定されていると、メッセージに有効期限の絶対時間が適用されます。これは、キューからメッセージが削除される絶対時間です。 有効期限の絶対時間は、キュー マネージャ プロセスが存在するマシン クロックによって決定されます。
有効期限の絶対時間は、EXP-TIME に格納された値で示されます。EXP-TIME は、time(2) または mktime(3C) によって生成された絶対時間に設定されなければなりません (世界協定時 (UTC) 1970 年 1 月 1 日 00:00:00 から経過した秒数)。 キューへの登録操作の時間より早い絶対時間が指定されると、操作は成功しますが、メッセージはしきい値の計算の対象になりません。有効期限の時間がメッセージの使用可能時間より前の場合、使用可能時間が有効期限の切れる時間より前になるようにいずれかの時間を変更しない限り、メッセージをキューから取り出すことはできません。また、これらのメッセージがキューからの取り出しの対象になったことがなくても、有効期限が切れるとキューから削除されます。トランザクション中にメッセージの期限が切れてもトランザクションは失敗しません。トランザクション内でキューへの登録、またはキューからの取り出し中に有効期限が切れたメッセージは、トランザクションが終了した時点でキューから削除されます。メッセージの有効期限が切れたことの通知は行われません。 TPQEXPTIME-ABS、TPQEXPTIME-REL、TPQEXPTIME-NONE、TPQNOEXPTIME のいずれかを設定しなければなりません。

TPQEXPTIME-REL

この値が設定されていると、メッセージに有効期限の相対時間が適用されます。これは、メッセージがキューに到達してから、キューから削除されるまでの秒数です。有効期限の相対時間は、EXP-TIME に格納された値で示されます。
有効期限の時間がメッセージの使用可能時間より前の場合、使用可能時間が有効期限の切れる時間より前になるようにいずれかの時間を変更しない限り、メッセージをキューから取り出すことはできません。また、これらのメッセージがキューからの取り出しの対象になったことがなくても、有効期限が切れるとキューから削除されます。メッセージがトランザクション内にあるときに期限切れになった場合、それによってトランザクションが異常終了することはありません。トランザクション内でキューへの登録、またはキューからの取り出し中に有効期限が切れたメッセージは、トランザクションが終了した時点でキューから削除されます。メッセージの有効期限が切れたことの通知は行われません。 TPQEXPTIME-ABS、TPQEXPTIME-REL、TPQEXPTIME-NONE、TPQNOEXPTIME のいずれかを設定しなければなりません。

TPQEXPTIME-NONE

この値が設定されていると、メッセージの有効期限が無期限になります。このフラグは、ターゲットのキューに対応付けられているデフォルトの有効期限の方針を上書きします。メッセージを削除するには、管理インタフェースを介してキューから取り出すか、または削除します。TPQEXPTIME-ABS、TPQEXPTIME-REL、TPQEXPTIME-NONE、TPQNOEXPTIME のいずれかを設定しなければなりません。

TPQNOEXPTIME

この値が設定されていると、ターゲットのキューに対応付けられているデフォルトの有効期限の時間がメッセージに適用されます。TPQEXPTIME-ABS、TPQEXPTIME-REL、TPQEXPTIME-NONE、TPQNOEXPTIME のいずれかを設定しなければなりません。

このほかに、TPQUEDEF-REC のメンバー APPL-RETURN-CODE にユーザ戻りコードを設定することができます。この値は、メッセージをキューから取り出すために TPDEQUEUE() を呼び出すアプリケーションに返されます。

TPENQUEUE() からの出力では、次のフィールドが TPQUEDEF-REC 構造体に設定されます。 

05 DIAGNOSTIC           PIC S9(9) COMP-5.
05 MSGID                PIC X(32).

TPENQUEUE() からの出力情報を制御する TPQUEDEF-REC の有効な設定を次に示します。TPENQUEUE() の呼び出し時にこの値が設定されている場合、Oracle Tuxedo /Q サーバ TMQUEUE(5) は、レコード内の対応する要素にメッセージ識別子を挿入します。TPENQUEUE() の呼び出し時にこの値が設定されていない場合、TMQUEUE() は、レコード内の対応する要素にメッセージ識別子を挿入しません。

TPQMSGID

この値が設定され、TPENQUEUE() の呼び出しが正常終了した場合は、メッセージ識別子が MSGID に格納されます。メッセージ識別子の値は 32 バイト全体が意味を持つので、MSGID に格納される値は、たとえば NULL 文字を埋め込むなどして、完全に初期化する必要があります。初期化に使用される実際の埋め込み文字は、Oracle Tuxedo /Q コンポーネントのリリースによって異なります。TPQNOMSGID が設定されている場合、メッセージ識別子は使用できません。

制御構造体の残りのメンバーは、TPENQUEUE() への入力では使用しません。

TPENQUEUE() の呼び出しが失敗し、TP-STATUS に TPEDIAGNOSTIC が設定された場合、失敗の原因を示す値が DIAGNOSTIC に返されます。次は、返される値です。

[QMEINVAL]

無効な設定値が指定されています。

[QMEBADRMID]

無効なリソース マネージャ識別子が指定されています。

[QMENOTOPEN]

リソース マネージャが現在オープンされていません。

[QMETRAN]

呼び出しがトランザクション モードではないか、または TPNOTRAN を指定して呼び出しが行われたため、キューにメッセージを登録するトランザクションを開始したときに、エラーが発生しました。この診断は、Oracle Tuxedo リリース 7.1 以降のキュー マネージャでは返されません。

[QMEBADMSGID]

無効なメッセージ識別子が指定されています。

[QMESYSTEM]

システム エラーが発生しました。エラーの正確な内容がログ ファイルに書き込まれます。

[QMEOS]

オペレーティング システムのエラーが発生しました。

[QMEABORTED]

操作がアボートされました。アボートされた操作がグローバル トランザクション内で実行されていた場合、グローバル トランザクションは「ロールバックのみ」とマークされます。それ以外の場合、キュー マネージャは操作をアボートします。

[QMEPROTO]

トランザクションの状態がアクティブではないときに、キューへの登録が行われました。

[QMEBADQUEUE]

無効または削除されたキューの名前が指定されています。

[QMENOSPACE]

キュー上に領域がないなどリソース不足が原因で、サービスの品質 (永続的な記憶域または非永続的な記憶域) が指定されたメッセージがキューに登録されませんでした。次のいずれかのリソース設定を超えると、QMENOSPACE が返されます。(1) キュー スペースに割り当てられたディスク容量 (永続的)、(2) キュー スペースに割り当てられたメモリ容量 (非永続的)、(3) 同時にアクティブ状態になるトランザクションの最大数 (キュー スペースで許容される数であることが必要です)、(4) キュー スペースに一度に入れることができる最大メッセージ数、(5) キューイング サービス コンポーネントが処理できる並列アクションの最大数、または (6) キューイング サービス コンポーネントを同時に使用できる認証されたユーザの最大数。

[QMERELEASE]

新機能がサポートされていないバージョンの Oracle Tuxedo システムのキュー マネージャに対して、メッセージのキューへの登録が試みられました。

[QMESHARE]

指定されたキューのメッセージの登録時に、そのキューが別のアプリケーションによって排他的にオープンされています。別のアプリケーションとは、Oracle Tuxedo システム以外の Oracle 製品に基づくもので、キューをオープンして、キューイング サービス API (QSAPI) を使用して読み取りおよび書き込み、またはそのいずれかを排他的に行っています。

キューの順序の無効化

キューの作成時に、管理者が TPENQUEUE() 呼び出しでキュー上のメッセージの順序を無効にできるようにした場合、次の 2 つの方法でこの無効機能を利用できます。この 2 つの方法は、相互に排他的です。TPQTOP を設定すると、メッセージをキューの先頭に置くことができます。または、TPQBEFOREMSGID、MSGID に既存メッセージの ID を設定して、メッセージを特定の既存のメッセージの前に置くこともできます。この方法では、メッセージ ID を使用できるように、以前の呼び出しで取得されたメッセージ ID が保存されていることが必要です。管理者は、キューでサポートされている方法を通知する必要があります。キューは、この 2 つのいずれかまたは両方を使用できるように、あるいはどちらも使用できないように作成できます。

キューの優先順位の無効化

PRIORITY に値を設定して、メッセージの優先順位を指定することができます。この値は、1 以上 100 以下の範囲でなければなりません。数値が高いほど優先順位も高くなります。つまり、UNIX の nice コマンドで指定される値とは異なります。キューの順序付けパラメータの中に PRIORITY が含まれていない場合、ここで優先順位を設定しても取り出しの順序には影響しません。ただし、優先順位の値は保持されるので、メッセージがキューから取り出されるときに検査されます。

メッセージの使用可能時間の設定

DEQ-TIME に、絶対時間またはキューへの登録が完了してからの相対時間として、メッセージが処理されるまで時間を指定できます。TPQTIME-ABS または TPQTIME-REL のいずれかを設定して、値の処理方法を指定できます。キューは、time を順序付けの基準として作成することができます。その場合、メッセージは使用可能時間によって順序付けされます。

次のコード例は、相対時間を使用して、メッセージをキューに登録する方法を示しています。このメッセージは、60 秒後に処理対象になります。 

  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 "QSPACE1" TO QSPACE-NAME IN TPQUEDEF-REC.
  MOVE "Q1" 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.
  SET TPQDEFAULT IN TPQUEDEF-REC TO TRUE.
  SET TPQTIME-REL IN TPQUEDEF-REC TO TRUE.
  MOVE 60 TO DEQ-TIME IN TPQUEDEF-REC.
  SET TPQNOPRIORITY IN TPQUEDEF-REC TO TRUE.
  SET TPQNOCORRID IN TPQUEDEF-REC TO TRUE.
  SET TPQNOREPLYQ IN TPQUEDEF-REC TO TRUE.
  SET TPQNOFAILUREQ IN TPQUEDEF-REC TO TRUE.
  SET TPQMSGID 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 "TPENQUEUE" USING
          TPQUEDEF-REC
          TPTYPE-REC
          USER-DATA-REC
          TPSTATUS-REC.

TPENQUEUE() およびトランザクション

TPENQUEUE() の呼び出し側がトランザクション モードにある場合に、TPTRAN が設定されていると、キューへの登録は呼び出し側のトランザクション内で行われます。呼び出し側は、TPENQUEUE() が成功したか失敗したかによって、メッセージがキューに登録されたかどうかを判断できます。呼び出しが正常に行われると、メッセージがキューに登録されたことが保証されます。呼び出しが失敗すると、メッセージがキューに登録された部分も含めて、トランザクションがロールバックされます。

TPENQUEUE() の呼び出し側がトランザクション モードにない場合、または TPNOTRAN が設定されている場合、メッセージは呼び出し側のトランザクションとは別のトランザクションでキューに登録されます。TPENQUEUE() への呼び出しが正常な戻り値を返した場合、メッセージがキューに登録されたことが保証されます。TPENQUEUE() の呼び出しが通信エラーまたはタイムアウトによって失敗した場合は、その障害がメッセージ登録の前に発生したのか後に発生したのか、呼び出し側には判断できません。

呼び出し側がトランザクション モードにないときに TPNOTRAN を指定しても意味がありません。

 

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

次は、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(3cbl) の処理を制御するいくつかの重要な引数があります。その一部について、以下に説明します。

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.

TMQUEUE(5) リファレンス ページの例では、サーバを作成してコンフィグレーション ファイルで指定する際に、サービスのエリアスを指定する方法が示されています。「サンプル アプリケーション」のサンプル プログラムでも、サービスのエリアスが指定されています。

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() 呼び出しの処理方法を Oracle Tuxedo システムに通知するために使用されます。次は、有効な設定です。

TPNOTRAN

呼び出し側がトランザクション モードにある場合、この設定はキューからのメッセージの取り出しが別のトランザクション内で行われることを指示します。TPNOTRAN または TPTRAN のいずれかを設定しなければなりません。

TPTRAN

呼び出し側がトランザクション モードにある場合、この設定はキューからのメッセージの取り出しが同じトランザクション内で行われることを指定します。TPNOTRAN または TPTRAN のいずれかを設定しなければなりません。

TPNOBLOCK

ブロッキング状態が存在する場合、メッセージはキューから取り出されません。TPNOBLOCK が設定されている場合に、メッセージの転送先である内部バッファがいっぱいであるなどのブロッキング状態が存在すると、呼び出しは失敗し、tperrno(5) に TPEBLOCK が設定されます。TPNOBLOCK が設定されている場合に、ターゲットのキューが別のアプリケーションによって排他的にオープンされているというブロッキング状態が存在すると、呼び出しは失敗し、tperrno() に TPEDIAGNOSTIC が設定され、TPQCTL 構造体の診断フィールドに QMESHARE が設定されます。後者の場合、Oracle Tuxedo システム以外の Oracle Products に基づくほかのアプリケーションが、キューイング サービス API (QSAPI) を使用して読み取りと書き込み、またはそのいずれかを排他的に行うためにキューをオープンしています。TPNOBLOCK または TPBLOCK のいずれかを設定しなければなりません。

TPBLOCK

TPBLOCK が設定されている場合に、ブロッキング状態が存在すると、その状態が解消されるかタイムアウト (トランザクション タイムアウトまたはブロッキング タイムアウト) が発生するまで、呼び出し側はブロックされます。TPQWAIT が設定されている場合、このブロッキング条件にはキュー自体でのブロッキングは含まれません。TPNOBLOCK または TPBLOCK のいずれかを設定しなければなりません。

TPNOTIME

この値が設定されていると、呼び出しにブロッキング タイムアウトが適用されないことを示します。ただし、トランザクション タイムアウトは発生する可能性があります。TPNOTIME または TPTIME のいずれかを設定しなければなりません。

TPTIME

この値が設定されていると、呼び出しにブロッキング タイムアウトが適用されることを示します。TPNOTIME または TPTIME のいずれかを設定しなければなりません。

TPNOCHANGE

この値が設定されていると、DATA-REC のレコード タイプは変更できません。つまり、受信したレコードのタイプおよびサブタイプは、レコード DATA-REC のタイプおよびサブタイプと一致しなければなりません。TPNOCHANGE または TPCHANGE のいずれかを設定しなければなりません。

TPCHANGE

デフォルトでは、レコード DATA-REC とは異なるタイプのレコードが受信されると、受信側が着信レコードのタイプを識別する限り、DATA-REC のレコード タイプは、受信されたレコードのタイプに変更されます。つまり、受信したレコードのタイプおよびサブタイプは、レコード DATA-REC のタイプおよびサブタイプと一致しなければなりません。TPNOCHANGE または TPCHANGE のいずれかを設定しなければなりません。

TPSIGRSTRT

この値が設定されていると、基となるシステム コールがシグナルによって中断された場合、中断されたシステム コールが再度呼び出されることを指定します。TPSIGRSTRT または TPNOSIGRSTRT のいずれかを設定しなければなりません。

TPNOSIGRSTRT

この値が設定されている場合にシグナルが受信されると、呼び出しは失敗し、TP-STATUS に TPEGOTSIG が設定されます。TPSIGRSTRT または TPNOSIGRSTRT のいずれかを設定しなければなりません。

TPQUEDEF-REC 構造体

TPDEQUEUE() の最初の引数は、TPQUEDEF-REC 構造体です。TPQUEDEF-REC 構造体には、アプリケーションで使用されるメンバーと Oracle Tuxedo システムで使用されるメンバーがあり、アプリケーション プログラムとキュー機能間の両方向でパラメータがやり取りされます。TPDEQUEUE() を呼び出すクライアントは、設定値を使用して、システム側で入力する必要のあるメンバーをマークします。前述のように、この構造体は TPENQUEUE() でも使用されます。一部のメンバーは、TPENQUEUE() だけに適用されます。この構造体全体のサンプル コードは、「TPQUEDEF-REC 構造体」に示されています。

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

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

次は、TPDEQUEUE() の入力情報を制御する TPQUEDEF-REC の有効な値です。

TPQGETNEXT

この値が設定されていると、デフォルトのキューの順序を使用して、キュー上にある次のメッセージが取り出されます。TPQGETNEXT、TPQGETBYMSGID、TPQGETBYCORRID のいずれかを設定しなければなりません。

TPQGETBYMSGID

この値が設定されていると、MSGID で識別されるメッセージが取り出されます。メッセージ識別子は、以前に呼び出された TPENQUEUE() 呼び出しによって返されます。メッセージがあるキューから別のキューに移動された場合、メッセージ識別子は無効になります。また、メッセージ識別子の値は 32 バイト全体が意味を持つので、MSGID で識別される値は、たとえば空白を埋め込むなどして、完全に初期化する必要があります。
TPQGETNEXT、TPQGETBYMSGID、TPQGETBYCORRID のいずれかを設定しなければなりません。

TPQGETBYCORRID

この値が設定されていると、CORRID で識別されるメッセージが取り出されます。相関識別子は、アプリケーションが TPENQUEUE() でキューにメッセージを登録したときに指定されます。相関識別子の値は 32 バイト全体が意味を持つので、CORRID で識別される値は、たとえば空白を埋め込むなどして、完全に初期化する必要があります。
TPQGETNEXT、TPQGETBYMSGID、TPQGETBYCORRID のいずれかを設定しなければなりません。

TPQWAIT

この値が設定されていると、キューが空の場合はエラーが返されません。代わりに、メッセージを取り出すことができるようになるまで、プロセスが待機します。待機しない場合は、TPQNOWAIT を設定します。TPQWAIT が TPQGETBYMSGID または TPQGETBYCORRID と併せて設定されている場合、指定されたメッセージ識別子または相関識別子を持つメッセージがキューに存在しないときは、エラーが返されません。代わりに、基準を満たすメッセージを取り出すことができるようになるまで、プロセスは待機します。プロセスには呼び出し側のトランザクション タイムアウトの影響を受けます。また、トランザクション モードでない場合、プロセスは TMQUEUE プロセスで -t オプションによって指定されたタイムアウトの影響を受けます。
基準に一致するメッセージをすぐに取り出すことができない場合に、設定されているアクション リソースの限界に達すると、TPDEQUEUE は失敗し、TP-STATUS に TPEDIAGNOSTIC が設定され、DIAGNOSTIC に QMESYSTEM が設定されます。 TPQWAIT 制御パラメータを指定する TPDEQUEUE() の各要求では、条件を満たすメッセージがすぐに利用できない場合、キュー マネージャ (TMQUEUE) のアクション オブジェクトを使用できる必要があります。アクション オブジェクトを利用できない場合、TPDEQUEUE() 要求は失敗します。利用できるキュー マネージャのアクション数は、キュー スペースの作成時または変更時に指定されます。待機中のキューからの取り出し要求が完了すると、対応するアクション オブジェクトは別の要求に使用できるようになります。

TPQPEEK

TPQPEEK が設定されていると、指定されたメッセージが読み取られてもキューから削除されません。TPNOTRAN フラグを設定する必要があります。トランザクション内でメッセージをキューに登録、またはキューから取り出す場合、そのトランザクションが完了する前に、メッセージを読み取ることはできません。
あるスレッドが TPQPEEK を使用してメッセージを破棄せずにキューから取り出す場合、その取り出し要求をシステムが処理している短時間の間、非ブロッキング状態のほかのメッセージ取り出し操作にメッセージが認識されないことがあります。たとえば、特定の選択基準 (メッセージ識別子や相関識別子など) を使用してメッセージをキューから取り出す操作が、破棄せずに取り出しが現在行われているメッセージを探している場合などがあります。

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() が完了します。

TPQPRIORITY

この値が設定され、TPDEQUEUE() の呼び出しが成功し、メッセージが明示的な優先順位でキューに登録された場合は、その優先順位が PRIORITY に格納されます。優先順位は 1 以上 100 以内の範囲内で、数値が高いほど優先順位も高くなります。つまり、高い数値のメッセージが低い数値のメッセージよりも先にキューから取り出されます。TPQNOPRIORITY が設定されている場合、優先順位は使用できません。
メッセージのキューへの登録時に優先順位が明示的に指定されていない場合、そのメッセージの優先順位は 50 になります。

TPQMSGID

この値が設定されている場合に、TPDEQUEUE() の呼び出しが成功すると、メッセージ識別子が MSGID に格納されます。メッセージ識別子の値は、32 バイト全体が意味を持ちます。TPQNOMSGID が設定されている場合、メッセージ識別子は使用できません。

TPQCORRID

この値が設定され、TPDEQUEUE() の呼び出しが成功し、メッセージが相関識別子を使用してキューに登録された場合、その相関識別子は CORRID に格納されます。相関識別子の値は、32 バイト全体が意味を持ちます。Oracle Tuxedo /Q から渡されるメッセージに対するすべての応答は、元のメッセージの相関識別子を持ちます。TPQNOCORRID が設定されている場合、相関識別子は使用できません。

TPQDELIVERYQOS

この値が設定され、TPDEQUEUE() の呼び出しが成功し、メッセージがサービスの配信品質と共にキューに登録された場合、TPQUEQOS-DELIVERY-FLAG で指定されるフラグ TPQQOSDELIVERYDEFAULTPERSIST、TPQQOSDELIVERYPERSISTENT、または TPQQOSDELIVERYNONPERSISTENT がサービスの配信品質を示します。TPQNODELIVERYQOS が設定されている場合、サービスの配信品質は使用できません。
メッセージのキューへの登録時にサービスの配信品質が明示的に指定されていない場合、ターゲットのキューのデフォルトの配信方針がメッセージに対するサービスの配信品質を指定します。

TPQREPLYQOS

この値が設定され、TPDEQUEUE() の呼び出しが成功し、メッセージがサービスの応答品質と共にキューに登録された場合、TPQUEQOS-REPLY-FLAG で指定されるフラグ TPQQOSREPLYDEFAULTPERSIST、TPQQOSREPLYPERSISTENT、または TPQQOSREPLYNONPERSISTENT がサービスの配信品質を示します。TPQNOREPLYQOS が設定されている場合、サービスの応答品質は使用できません。
メッセージがキューに入れられたときにサービスの応答品質が明示的に指定されていない場合、REPLYQUEUE キューのデフォルトの配信ポリシーが応答に対するサービスの配信品質を指定します。デフォルトの配信方針は、メッセージに対する応答がキューに登録されるときに決定されます。つまり、元のメッセージがキューに登録されてから応答が登録されるまでの間に、応答キューのデフォルトの配信方針が変更された場合、応答が最後に登録される時点で有効な方針が使用されます。

TPQREPLYQ

この値が設定され、TPDEQUEUE() の呼び出しが成功し、メッセージが応答キューと共にキューに登録された場合、その応答キューの名前が REPLYQUEUE に格納されます。メッセージへの応答は、要求メッセージと同じキュー スペース内の指定されたキューに登録されます。TPQNOREPLYQ が設定されている場合、応答キューは使用できません。

TPQFAILUREQ

この値が設定され、TPDEQUEUE() の呼び出しが成功し、メッセージが異常終了キューと共にキューに登録された場合、その異常終了キューの名前が FAILUREQUEUE に格納されます。異常終了メッセージは、要求メッセージと同じキュー スペース内の指定された異常終了キューに登録されます。TPQNOFAILUREQ が設定されている場合、異常終了キューは使用できません。

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

TPDEQUEUE() の呼び出しが失敗し、TP-STATUS に TPEDIAGNOSTIC が設定された場合、失敗の原因を示す値が DIAGNOSTIC に返されます。DIAGNOSTIC の有効な設定値には、「TPQUEDEF-REC 構造体」に示されている TPENQUEUE() の値 (QMENOSPACE と QMERELEASE を除く) のほかに、次のものがあります。

[QMENOMSG]

キューから取り出せるメッセージはありません。メッセージがキュー上に存在し、別のアプリケーション プロセスがこのメッセージをキューから読み取った可能性があることに注意してください。その場合、その別のプロセスがトランザクションをロールバックしたときに、メッセージがキューに戻されます。

[QMEINUSE]

メッセージ識別子または相関識別子を使用してメッセージをキューから取り出す際に、指定されたメッセージが別のトランザクションによって使用されています。それ以外の場合、現在キューにあるすべてのメッセージは、ほかのトランザクションによって使用されています。この診断は、Oracle Tuxedo リリース 7.1 以降のキュー マネージャでは返されません。

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 を通して呼び出されたサービスからの応答をキューから取り出す手順

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

  1. 前提条件として、キュー スペースに応答キューおよび異常終了キューがあることが必要です。アプリケーションは、相関識別子の内容について一貫していなければなりません。サービスは、論理的な失敗の場合に TPSUCCESS を返し、TPRETURN の TPSVCRET-REC 引数内の APPL-CODE に情報を示すコードを返すようにコーディングします。
  2. TPENQUEUE() を呼び出してキューにメッセージを登録する際に、次を設定します。 
    3. TPQCORRID      TPQREPLYQ
    TPQFAILUREQ    TPQMSGID

    この呼び出しを行う前に、CORRID、REPLYQUEUE、および FAILUREQUEUE の値を設定します。呼び出しから制御が戻ったら、CORRID を保存します。

  3. TPDEQUEUE() を呼び出して応答を確認する際に、QNAME に応答キューを指定し、次を設定します。
    4. TPQCORRID       TPQREPLYQ
    TPQFAILUREQ     TPQMSGID
    TPQGETBYCORRID

    この呼び出しを行う前に、保存した相関識別子を使用して CORRID に入力します。TPDEQUEUE() の呼び出しが失敗し、TP-STATUS に TPEDIAGNOSTIC が設定された場合、詳しい情報を DIAGNOSTIC から取得できます。エラー コード QMENOMSG を受信した場合、キューから取り出すことのできるメッセージがなかったことを示します。

  4. もう 1 つの TPDEQUEUE() 呼び出しを設定します。この呼び出しでは、QNAME が異常終了キューの名前を指すようにし、次を設定します。 
    5. TPQCORRID       TPQREPLYQ
    TPQFAILUREQ     TPQMSGID
    TPQGETBYCORRID

    TPQCORRID に相関識別子を挿入します。呼び出しから制御が戻ったら、LEN を確認してデータを受信したかどうかを確認し、APPL-RETURN-CODE を調べてサービスがユーザ戻り値を返したどうかを確認します。

 

メッセージの順次処理

メッセージの順次処理は、あるサービスがそのトランザクションがコミットされる前に、連鎖的に次のサービス用にメッセージをキューに登録することによって行われます。最初の発信元のプロセスは、reply_queue に対する一連の TPDEQUEUE() 呼び出しによって順次処理の進行状況を追跡できます。ただし、各メンバーが同じ相関識別子を使用し、長さ 0 の応答を返すことが必要です。

また、非請求通知を使用して、順次処理全体が成功したという通知を最初の発信元に返すこともできます。順次処理の最後のトランザクションが TPCOMMIT で終了したことを確認するには、TPQUEDEF-REC 構造体で渡されるクライアント識別子を使用して、TPNOTIFY を呼び出す操作を追加します。最初の発信元であるクライアントは、TPSETUNSOL を呼び出して、使用されている非請求メッセージ ハンドラを指定しておかなければなりません。

ピア ツー ピア通信でのキューの使用

キューへのメッセージの登録およびキューからのメッセージの取り出しに関するこれまでの説明では、キューが要求/応答の一形態として使用されていることが暗黙の前提になっていました。メッセージ自体はサービス要求である必要はありません。キュー機能は、あるプロセスから別のプロセスに、サービス要求と同じように効果的にデータを転送できます。アプリケーション間またはクライアント間のこの通信方式は、ピア ツー ピア通信と呼ばれます。

使用するアプリケーションが、このような目的で Oracle Tuxedo /Q を使用することに適している場合は、管理者に別のキューを作成してもらい、そのキューからメッセージを取り出す独自の受信用プログラムをコーディングします。


  ページの先頭       前  次