ATMI /Qコンポーネントの使用

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

このトピックには次の項が含まれます:

はじめに

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

前提知識

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

リクエストの発信元

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

キュー・スペースと同じマシン、またはネットワーク上の別のマシンにあるクライアントまたはサーバー。
会話型プログラム。ただし、キュー(または、TMQUEUE(5)サーバー)との会話接続は確立できません。
ネイティブ側の代理プロセスを介するワークステーション・クライアント。管理インタフェースも完全にサーバー側にあります。

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

ここでは、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"
or
        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製品に基づくほかのアプリケーションが、キューイング・サービス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()でも使用され、一部のメンバーは、アプリケーションがこの関数を呼び出すまで使用されません。リスト4-1は、この構造体全体を示しています。

リスト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(127).
        05 QSPACE-NAME          PIC X(127).
        05 REPLYQUEUE           PIC X(127).
        05 FAILUREQUEUE         PIC X(127).
        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がここで使用できるように保存されたことが前提になります。管理者は、キューでサポートされている方法を通知する必要があります。キューは、この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"
or
        CLOPT = "-s TMQUEUE"

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

`TPNOTRAN`

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

`TPTRAN`

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

`TPNOBLOCK`

ブロッキング状態が存在すると、メッセージはキューから取り出されません。TPNOBLOCKが設定されている場合に、メッセージの転送先である内部バッファがいっぱいであるなどのブロッキング状態が存在すると、呼出しは失敗し、tperrno(5)にTPEBLOCKが設定されます。TPNOBLOCKが設定されている場合に、ターゲットのキューが別のアプリケーションによって排他的にオープンされているというブロッキング状態が存在すると、呼出しは失敗し、tperrno()にTPEDIAGNOSTICが設定され、TPQCTL構造体の診断フィールドにQMESHAREが設定されます。後者の場合、Oracle Tuxedoシステム以外のOracle製品に基づくほかのアプリケーションが、キューイング・サービス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(127). 
05 FAILUREQUEUE              PIC X(127). 
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種類のエラーを区別しておきます。

リクエストされたサービスに転送するために、TMQFORWARD(5)がメッセージをキューから取り出すときに発生するエラー
リクエストを処理するサービスに発生するエラー

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

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

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

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

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

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

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

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

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

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

TPQCORRID      TPQREPLYQ
TPQFAILUREQ    TPQMSGID

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

TPDEQUEUE()を呼び出して応答を確認する際に、QNAMEに応答キューを指定し、次を設定します。

TPQCORRID       TPQREPLYQ
TPQFAILUREQ     TPQMSGID
TPQGETBYCORRID

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

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

TPQCORRID       TPQREPLYQ
TPQFAILUREQ     TPQMSGID
TPQGETBYCORRID

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

メッセージの順次処理

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

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

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

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

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

ATMI /Qコンポーネントの使用

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

はじめに

前提知識

リクエストの発信元

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

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

TPENQUEUE()の引数

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

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

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

TPENQUEUE(): TPQUEDEF-RECの設定値

TPNOTRAN

TPTRAN

TPNOBLOCK

TPBLOCK

TPNOTIME

TPTIME

TPSIGRSTRT

TPNOSIGRSTRT

TPQUEDEF-REC構造体

TPQTOP

TPQBEFOREMSGID

TPQTIME-ABS

TPQTIME-REL

TPQPRIORITY

TPQCORRID

TPQREPLYQ

TPQFAILUREQ

TPQDELIVERYQOSTPQREPLYQOS

TPQQOSDELIVERYDEFAULTPERSISTTPQQOSREPLYDEFAULTPERSIST

TPQQOSDELIVERYPERSISTENTTPQQOSREPLYPERSISTENT

TPQQOSDELIVERYNONPERSISTENTTPQQOSREPLYNONPERSISTENT

TPQEXPTIME-ABS

TPQEXPTIME-REL

TPQEXPTIME-NONE

TPQNOEXPTIME

TPQMSGID

[QMEINVAL]

[QMEBADRMID]

[QMENOTOPEN]

[QMETRAN]

[QMEBADMSGID]

[QMESYSTEM]

[QMEOS]

[QMEABORTED]

[QMEPROTO]

[QMEBADQUEUE]

[QMENOSPACE]

[QMERELEASE]

[QMESHARE]

キューの順序の無効化

キューの優先度の無効化

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

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

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

TPDEQUEUE()の引数

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

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

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

TPDEQUEUE(): TPQUEDEF-RECの設定値

TPNOTRAN

TPTRAN

TPNOBLOCK

TPBLOCK

TPNOTIME

TPTIME

TPNOCHANGE

TPCHANGE

TPSIGRSTRT

TPNOSIGRSTRT

TPQUEDEF-REC構造体

TPQGETNEXT

TPQGETBYMSGID

TPQGETBYCORRID

TPQWAIT

TPQPEEK

TPQPRIORITY

TPQMSGID

TPQCORRID

`TPNOTRAN`

`TPTRAN`

`TPNOBLOCK`

`TPBLOCK`

`TPNOTIME`

`TPTIME`

`TPSIGRSTRT`

`TPNOSIGRSTRT`

`TPQTOP`

`TPQBEFOREMSGID`

`TPQTIME-ABS`

`TPQTIME-REL`

`TPQPRIORITY`

`TPQCORRID`

`TPQREPLYQ`

`TPQFAILUREQ`

`TPQDELIVERYQOS TPQREPLYQOS`

`TPQQOSDELIVERYDEFAULTPERSIST TPQQOSREPLYDEFAULTPERSIST`

`TPQQOSDELIVERYPERSISTENT TPQQOSREPLYPERSISTENT`

`TPQQOSDELIVERYNONPERSISTENT TPQQOSREPLYNONPERSISTENT`

`TPQEXPTIME-ABS`

`TPQEXPTIME-REL`

`TPQEXPTIME-NONE`

`TPQNOEXPTIME`

`TPQMSGID`

[`QMEINVAL`]

[`QMEBADRMID`]

[`QMENOTOPEN`]

[`QMETRAN`]

[`QMEBADMSGID`]

[`QMESYSTEM`]

[`QMEOS`]

[`QMEABORTED`]

[`QMEPROTO`]

[`QMEBADQUEUE`]

[`QMENOSPACE`]

[`QMERELEASE`]

[`QMESHARE`]

`TPNOTRAN`

`TPTRAN`

`TPNOBLOCK`

`TPBLOCK`

`TPNOTIME`

`TPTIME`

`TPNOCHANGE`

`TPCHANGE`

`TPSIGRSTRT`

`TPNOSIGRSTRT`

`TPQGETNEXT`

`TPQGETBYMSGID`

`TPQGETBYCORRID`

`TPQWAIT`

`TPQPEEK`

`TPQPRIORITY`

`TPQMSGID`

`TPQCORRID`

`TPQDELIVERYQOS`

`TPQREPLYQOS`

`TPQREPLYQ`

`TPQFAILUREQ`

[`QMENOMSG`]

[`QMEINUSE`]