Oracle Tuxedo/Q COBOL言語プログラミング
キュー式メッセージ機能を使用するクライアント・プログラムまたはサーバー・プログラムをコーディングするOracle TUXEDOプログラマには、Oracle Tuxedo ATMIにバインドされたCOBOL言語についての知識が必要です。Oracle Tuxedoプログラミングに関する全般的な説明については、『COBOLを使用したOracle Tuxedo ATMIアプリケーションのプログラミング』
を参照してください。ATMI関数の詳細は、『Oracle Tuxedo ATMI COBOL関数リファレンス』
を参照してください。
Oracle Tuxedo /Qのキューにメッセージを登録する呼出しは、アプリケーションに関連付けられているあらゆるクライアント・プロセスまたはサーバー・プロセスから行うことができます。たとえば、次の発信元があります。
•
|
キュー・スペースと同じマシン、またはネットワーク上の別のマシンにあるクライアントまたはサーバー。
|
•
|
会話型プログラム。ただし、キュー(または、 TMQUEUE(5)サーバー)との会話接続は確立できません。
|
•
|
ネイティブ側の代理プロセスを介するワークステーション・クライアント。管理インタフェースも完全にサーバー側にあります。
|
図では、キューに入れられたメッセージが、サーバー
TMQFORWARD(5)によってキューから取り出され、処理のために(
TPCALL(3cbl)を介して)アプリケーション・サーバーに送信されています。
TPCALLに対する応答が受信されると、
TMQFORWARDは応答メッセージをキューに登録します。
TMQFORWARDは、キュー・スペースと既存のアプリケーション・サービスとの間にインタフェースを提供するので、アプリケーションにコードを追加する必要はありません。そのため、ここでは、クライアントとキュー・スペースとの間の処理を中心に説明します。
基本的なモデルについて説明し、その後でカスタマイズの例をいくつか示します。
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(): 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.
TPENQUEUE(): TPQUEDEF-REC引数内のQNAME
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または
TPTRANのいずれかが設定されていなければなりません。
呼出し側がトランザクション・モードにある場合、この設定はキューへのメッセージの登録が同じトランザクション内で行われることを指定します。
TPNOTRANまたは
TPTRANのいずれかが設定されていなければなりません。
ブロッキング状態が存在する場合、メッセージはキューに登録されません。
TPNOBLOCKが設定されている場合に、メッセージの転送先である内部バッファがいっぱいであるなどのブロッキング状態が存在すると、呼出しは失敗し、
tperrno(5)に
TPEBLOCKが設定されます。
TPNOBLOCKが設定されている場合に、ターゲットのキューが別のアプリケーションによって
排他的にオープンされているというブロッキング状態が存在すると、呼出しは失敗し、
tperrno()に
TPEDIAGNOSTICが設定され、
TPQCTL構造体の診断フィールドに
QMESHAREが設定されます。後者の場合、Oracle Tuxedoシステム以外のOracle製品に基づくほかのアプリケーションが、キューイング・サービスAPI (QSAPI)を使用して読取りと書き込み、またはそのいずれかを排他的に行うためにキューをオープンしています。
TPNOBLOCKまたは
TPBLOCKのいずれかを設定しなければなりません。
TPBLOCKが設定されている場合に、ブロッキング状態が存在すると、その状態が解消されるかタイムアウト(トランザクション・タイムアウトまたはブロッキング・タイムアウト)が発生するまで、呼出し側はブロックされます。
TPNOBLOCKまたは
TPBLOCKのいずれかを設定しなければなりません。
この設定は、呼出しにブロッキング・タイムアウトが適用されないことを示します。ただし、トランザクション・タイムアウトは発生する可能性があります。
TPNOTIMEまたは
TPTIMEのいずれかが設定されていなければなりません。
この設定は、呼出しにブロッキング・タイムアウトが適用されることを示します。
TPNOTIMEまたは
TPTIMEのいずれかが設定されていなければなりません。
この設定は、基となるシステム・コールがシグナルによって中断された場合、中断されたシステム・コールが再度呼び出されることを指定します。
TPSIGRSTRTまたは
TPNOSIGRSTRTのいずれかを設定しなければなりません。
この設定は、基となるシステム・コールがシグナルによって中断された場合、中断されたシステム・コールが再度呼び出されないことを指定します。呼出しは失敗し、
TP-STATUSに
TPEGOTSIGが設定されます。
TPSIGRSTRTまたは
TPNOSIGRSTRTのいずれかを設定しなければなりません。
TPQUEDEF-REC構造体には、アプリケーションで使用されるメンバーとOracle Tuxedoシステムで使用されるメンバーがあり、アプリケーション・プログラムとキュー式メッセージ機能間の両方向でパラメータがやり取りされます。これは、COBOL
COPYファイル内で定義されています。
TPQUEDEF-RECを呼び出すクライアントは、設定値を使用して、システム側で入力する必要のあるフィールドをマークします。この構造体は、
TPDEQUEUE()でも使用され、一部のメンバーは、アプリケーションがこの関数を呼び出すまで使用されません。
リスト4-1は、この構造体全体を示しています。
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の入力情報を制御するパラメータの有効な設定です。
この値を設定すると、キューの順序付けは無効になり、メッセージはキューの先頭に登録されます。このリクエストは、順序付けを無効にするようにキューが設定されているかどうかによって、使用できない場合があります。デフォルトのキューの順序を使用する場合は、
TPQDEFAULTを設定します。
TPQTOP、
TPQBEFOREMSGID、
TPQDEFAULTのいずれかを設定しなければなりません。
この値を設定すると、キューの順序は無効化され、メッセージは
MSGIDによって識別されるメッセージの前に登録されます。このリクエストは、順序付けを無効にするようにキューが設定されているかどうかによって、使用できない場合があります。デフォルトのキューの順序を使用する場合は、
TPQDEFAULTを設定します。
TPQTOP、
TPQBEFOREMSGID、
TPQDEFAULTのいずれかを設定しなければなりません。
メッセージ識別子の値は32バイト全体が意味を持つので、
MSGIDで識別される値は、たとえば空白を埋め込むなどして、完全に初期化する必要があります。
この値を設定すると、メッセージは、
DEQ-TIMEで指定された時間の経過後に処理されます。
DEQ-TIMEは、
time(2)または
mktime(3C)によって生成された絶対時間値、つまり世界協定時(UTC) 1970年1月1日00:00:00から経過した秒数を示します。絶対時間値も相対時間値も設定されていない場合は、
TPQNOTIMEを設定します。
TPQTIME-ABS、
TPQTIME-REL、
TPQNOTIMEのいずれかを設定しなければなりません。絶対時間は、キュー・マネージャ・プロセスが存在するマシン・クロックによって決定されます。
この値を設定すると、メッセージは、キューへの登録が完了してからの相対時間の経過後に処理されます。
DEQ-TIMEは、キューへの登録が完了した後、送信されたメッセージが処理されるまでの遅延秒数を指定します。絶対時間値も相対時間値も設定されていない場合は、
TPQNOTIMEを設定します。
TPQTIME-ABS、
TPQTIME-REL、
TPQNOTIMEのいずれかを設定しなければなりません。
この値が設定されていると、メッセージがキューに登録されるときの優先度が
PRIORITYに格納されます。優先度は、1から100以下の範囲である必要があります。数値が高いほど優先度も高くなり、高い数値のメッセージが低い数値のメッセージより先にキューから取り出されます。優先度によって順序付けられていないキューでは、この値は参考として使用されます。
TPQNOPRIORITYが設定されている場合、デフォルトでメッセージの優先度が50になります。
この値を設定すると、メッセージが
TPDEQUEUE()によってキューから取り出されるとき、
CORRIDに指定された相関識別子の値を使用することができます。この識別子は、キューに登録されるすべての応答メッセージまたは失敗メッセージに付加されるので、アプリケーションは応答を特定のリクエストに結び付けることができます。相関識別子を使用できない場合は、
TPQNOCORRIDを設定します。
相関識別子の値は32バイト全体が意味を持つので、
CORRIDに指定される値は、たとえば空白を埋め込むなどして、完全に初期化する必要があります。
この値が設定されていると、
REPLYQUEUEに指定された応答キューが、キューに入れられたメッセージに関連付けられます。メッセージへの応答はすべて、リクエスト・メッセージと同じキュー・スペース内の、指定されたキューに登録されます。応答キューの名前を使用できない場合は、
TPQNOREPLYQを設定します。
この値が設定されていると、
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共用メモリーが除去された場合、一時的メッセージは失われます。
この値が設定されていると、メッセージに有効期限の絶対時間が適用されます。これは、キューからメッセージが削除される絶対時間です。
有効期限の絶対時間は、キュー・マネージャ・プロセスが存在するマシン・クロックによって決定されます。
有効期限の絶対時間は、
EXP-TIMEに格納された値で示されます。
EXP-TIMEは、
time(2)または
mktime(3C)によって生成された絶対時間に設定されなければなりません(世界協定時(UTC) 1970年1月1日00:00:00から経過した秒数)。
キューへの登録操作の時間より早い絶対時間が指定されると、操作は成功しますが、メッセージはしきい値の計算の対象になりません。有効期限の時間がメッセージの使用可能時間より前の場合、使用可能時間が有効期限の切れる時間より前になるようにいずれかの時間を変更しないかぎり、メッセージをキューから取り出すことはできません。また、これらのメッセージがキューからの取出しの対象になったことがなくても、有効期限が切れるとキューから削除されます。トランザクション中にメッセージの期限が切れてもトランザクションは失敗しません。トランザクション内でキューへの登録、またはキューからの取出し中に有効期限が切れたメッセージは、トランザクションが終了した時点でキューから削除されます。メッセージの有効期限が切れたことの通知は行われません。
TPQEXPTIME-ABS、
TPQEXPTIME-REL、
TPQEXPTIME-NONE、
TPQNOEXPTIMEのいずれかを設定しなければなりません。
この値が設定されていると、メッセージに有効期限の相対時間が適用されます。これは、メッセージがキューに
到達してから、キューから削除されるまでの秒数です。有効期限の相対時間は、
EXP-TIMEに格納された値で示されます。
有効期限の時間がメッセージの使用可能時間より前の場合、使用可能時間が有効期限の切れる時間より前になるようにいずれかの時間を変更しないかぎり、メッセージをキューから取り出すことはできません。また、これらのメッセージがキューからの取出しの対象になったことがなくても、有効期限が切れるとキューから削除されます。メッセージがトランザクション内にあるときに期限切れになった場合、それによってトランザクションが異常終了することはありません。トランザクション内でキューへの登録、またはキューからの取出し中に有効期限が切れたメッセージは、トランザクションが終了した時点でキューから削除されます。メッセージの有効期限が切れたことの通知は行われません。
TPQEXPTIME-ABS、
TPQEXPTIME-REL、
TPQEXPTIME-NONE、
TPQNOEXPTIMEのいずれかを設定しなければなりません。
この値を設定すると、メッセージが期限切れになることはありません。このフラグは、ターゲットのキューに関連付けられているデフォルトの有効期限のポリシーをオーバーライドします。メッセージを削除するには、管理用のインタフェースを使用して、キューからメッセージを取り出すか削除します。
TPQEXPTIME-ABS、
TPQEXPTIME-REL、
TPQEXPTIME-NONE、
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()は、レコード内の対応する要素にメッセージ識別子を挿入しません。
この値が設定され、
TPENQUEUE()の呼出しが正常終了した場合は、メッセージ識別子が
MSGIDに格納されます。メッセージ識別子の値は32バイト全体が意味を持つので、
MSGIDに格納される値は、たとえばNULL文字を埋め込むなどして、完全に初期化する必要があります。初期化に使用される実際の埋め込み文字は、Oracle Tuxedo /Qコンポーネントのリリースによって異なります。
TPQNOMSGIDが設定されている場合、メッセージ識別子は使用できません。
制御構造体の残りのメンバーは、
TPENQUEUE()への入力では使用しません。
TPENQUEUE()の呼出しが失敗し、
TP-STATUSに
TPEDIAGNOSTICが設定された場合、失敗の原因を示す値が
DIAGNOSTICに返されます。次は、返される値です。
無効なリソース・マネージャ識別子が指定されました。
呼出しがトランザクション・モードではないか、または
TPNOTRANを指定して呼出しが行われたため、キューにメッセージを登録するトランザクションを開始したときに、エラーが発生しました。この診断は、Oracle Tuxedoリリース7.1以降のキュー・マネージャでは返されません。
システム・エラーが発生しました。エラーの正確な性質がログ・ファイルに書き込まれます。
オペレーティング・システムのエラーが発生しました。
操作が中断されました。中断された操作がグローバル・トランザクション内で実行されていた場合、グローバル・トランザクションは「ロールバックのみ」とマークされます。それ以外の場合、キュー・マネージャは操作を中断します。
トランザクションの状態がアクティブではないときに、キューへの登録が行われました。
無効または削除されたキューの名前が指定されています。
キュー上に領域がないなどリソース不足が原因で、サービスの品質(永続的な記憶域または非永続的な記憶域)が指定されたメッセージがキューに登録されませんでした。次のいずれかのリソース設定を超えると、
QMENOSPACEが返されます。(1)キュー・スペースに割り当てられたディスク容量(永続的)、(2)キュー・スペースに割り当てられたメモリー容量(非永続的)、(3)同時にアクティブ状態になるトランザクションの最大数(キュー・スペースで許容される数であることが必要です)、(4)キュー・スペースに一度に入れることができる最大メッセージ数、(5)キューイング・サービス・コンポーネントが処理できる並列アクションの最大数、または(6)キューイング・サービス・コンポーネントを同時に使用できる認証されたユーザーの最大数。
新機能がサポートされていないバージョンのOracle Tuxedoシステムのキュー・マネージャに対して、メッセージのキューへの登録が試みられました。
指定されたキューのメッセージの登録時に、そのキューが別のアプリケーションによって
排他的にオープンされています。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()の呼出し側がトランザクション・モードにある場合に、
TPTRANが設定されていると、キューへの登録は呼出し側のトランザクション内で行われます。呼出し側は、
TPENQUEUE()が成功したか失敗したかによって、メッセージがキューに登録されたかどうかを判断できます。呼出しが正常に行われると、メッセージがキューに登録されたことが保証されます。呼出しが失敗すると、メッセージがキューに登録された部分も含めて、トランザクションがロールバックされます。
TPENQUEUE()の呼出し側がトランザクション・モードにない場合、または
TPNOTRANが設定されている場合、メッセージは呼出し側のトランザクションとは別のトランザクションでキューに登録されます。
TPENQUEUE()への呼出し側が正常な戻り値を返した場合、メッセージがキューに登録されたことが保証されます。
TPENQUEUE()の呼出し側が通信エラーまたはタイムアウトによって失敗した場合は、その障害がメッセージ登録の前に発生したのか後に発生したのか、呼出し側には判断できません。
呼出し側がトランザクション・モードにないときに
TPNOTRANを指定しても意味がありません。
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(): 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"
サーバー・グループ
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()呼出しの処理方法をOracle Tuxedoシステムに通知するために使用されます。次は、有効な設定です。
呼出し側がトランザクション・モードにある場合、この設定はキューからのメッセージの取出しが呼出し側とは別のトランザクション内で行われることを指示します。
TPNOTRANまたは
TPTRANのいずれかが設定されていなければなりません。
呼出し側がトランザクション・モードにある場合、この設定はキューからのメッセージの取出しが同じトランザクション内で行われることを指定します。
TPNOTRANまたは
TPTRANのいずれかが設定されていなければなりません。
ブロッキング状態が存在すると、メッセージはキューから取り出されません。
TPNOBLOCKが設定されている場合に、メッセージの転送先である内部バッファがいっぱいであるなどのブロッキング状態が存在すると、呼出しは失敗し、
tperrno(5)に
TPEBLOCKが設定されます。
TPNOBLOCKが設定されている場合に、ターゲットのキューが別のアプリケーションによって
排他的にオープンされているというブロッキング状態が存在すると、呼出しは失敗し、
tperrno()に
TPEDIAGNOSTICが設定され、
TPQCTL構造体の診断フィールドに
QMESHAREが設定されます。後者の場合、Oracle Tuxedoシステム以外のOracle製品に基づくほかのアプリケーションが、キューイング・サービスAPI (QSAPI)を使用して読取りと書き込み、またはそのいずれかを排他的に行うためにキューをオープンしています。
TPNOBLOCKまたは
TPBLOCKのいずれかを設定しなければなりません。
TPBLOCKが設定されている場合に、ブロッキング状態が存在すると、その状態が解消されるかタイムアウト(トランザクション・タイムアウトまたはブロッキング・タイムアウト)が発生するまで、呼出し側はブロックされます。
TPQWAITが設定されている場合、このブロッキング条件にはキュー自体でのブロッキングは含まれません。
TPNOBLOCKまたは
TPBLOCKのいずれかを設定しなければなりません。
この値が設定されていると、呼出しにブロッキング・タイムアウトが適用されないことを示します。ただし、トランザクション・タイムアウトは発生する可能性があります。
TPNOTIMEまたは
TPTIMEのいずれかが設定されていなければなりません。
この値が設定されていると、呼出しにブロッキング・タイムアウトが適用されることを示します。
TPNOTIMEまたは
TPTIMEのいずれかが設定されていなければなりません。
この値が設定されていると、
DATA-RECのレコード・タイプは変更できません。つまり、受信したレコードのタイプおよびサブタイプは、レコード
DATA-RECのタイプおよびサブタイプと一致しなければなりません。
TPNOCHANGEまたは
TPCHANGEのいずれかを設定する必要があります。
デフォルトでは、レコード
DATA-RECとは異なるタイプのレコードが受信されると、受信側が着信レコードのタイプを識別するかぎり、
DATA-RECのレコード・タイプは、受信されたレコードのタイプに変更されます。つまり、受信したレコードのタイプおよびサブタイプは、レコード
DATA-RECのタイプおよびサブタイプと一致しなければなりません。
TPNOCHANGEまたは
TPCHANGEのいずれかを設定する必要があります。
この値が設定されていると、基となるシステム・コールがシグナルによって中断された場合、中断されたシステム・コールが再度呼び出されることを指定します。
TPSIGRSTRTまたは
TPNOSIGRSTRTのいずれかを設定しなければなりません。
この値が設定されている場合にシグナルが受信されると、呼出しは失敗し、
TP-STATUSに
TPEGOTSIGが設定されます。
TPSIGRSTRTまたは
TPNOSIGRSTRTのいずれかを設定しなければなりません。
TPDEQUEUE()の最初の引数は、
TPQUEDEF-REC構造体です。
TPQUEDEF-REC構造体には、アプリケーションで使用されるメンバーとOracle Tuxedoシステムで使用されるメンバーがあり、アプリケーション・プログラムとキュー式メッセージ機能間の両方向でパラメータがやり取りされます。
TPDEQUEUE()を呼び出すクライアントは、設定値を使用して、システム側で入力する必要のあるメンバーをマークします。前述のように、この構造体は
TPENQUEUE()でも使用されます。一部のメンバーは、TPENQUEUE()だけに適用されます。この構造体全体のサンプル・コードは、
4-6ページの「TPQUEDEF-REC構造体」に示されています。
TPDEQUEUE()への入力では、次のフィールドを
TPQUEDEF構造体に設定します。
05 MSGID PIC X(32).
05 CORRID PIC X(32).
次は、
TPDEQUEUE()の入力情報を制御する
TPQUEDEF-RECの有効な値です。
この値を設定すると、デフォルトのキューの順序で、キュー上の次のメッセージの取出しがリクエスされます。
TPQGETNEXT、
TPQGETBYMSGIDまたは
TPQGETBYCORRIDのいずれかを設定する必要があります。
この値を設定すると、
MSGIDで識別されるメッセージの取出しがリクエストされます。メッセージ識別子は、以前に呼び出された
TPENQUEUE()呼出しによって返されます。メッセージがあるキューから別のキューに移動された場合、メッセージ識別子は無効になります。また、メッセージ識別子の値は32バイト全体が意味を持つので、
MSGIDで識別される値は、たとえば空白を埋め込むなどして、完全に初期化する必要があります。
TPQGETNEXT、
TPQGETBYMSGIDまたは
TPQGETBYCORRIDのいずれかを設定する必要があります。
この値が設定されていると、
CORRIDで識別されるメッセージが取り出されます。相関識別子は、アプリケーションが
TPENQUEUE()でキューにメッセージを登録したときに指定されます。相関識別子の値は32バイト全体が意味を持つので、
CORRIDで識別される値は、たとえば空白を埋め込むなどして、完全に初期化する必要があります。
TPQGETNEXT、
TPQGETBYMSGIDまたは
TPQGETBYCORRIDのいずれかを設定する必要があります。
この値が設定されていると、キューが空の場合はエラーが戻されません。かわりに、メッセージを取り出せるようになるまで、プロセスは待機する必要があります。メッセージを取り出すことができるようになるまで待機しない場合は、
TPQNOWAITを設定します。
TPQWAITが
TPQGETBYMSGIDまたは
TPQGETBYCORRIDと組み合せて設定されている場合、指定されたメッセージ識別子または相関識別子を持つメッセージがキューに存在しないときは、エラーが戻されません。かわりに、基準を満たすメッセージを取り出せるようになるまで、プロセスは待機する必要があります。プロセスは呼出し側のトランザクション・タイムアウトの影響を受けますが、トランザクション・モードでない場合、プロセスは
TMQUEUEプロセスで
-tオプションによって指定されたタイムアウトの影響を受けます。
基準に一致するメッセージをすぐに取り出すことができない場合に、設定されているアクション・リソースの限界に達すると、
TPDEQUEUEは失敗し、
TP-STATUSに
TPEDIAGNOSTICが設定され、
DIAGNOSTICに
QMESYSTEMが設定されます。
TPQWAIT制御パラメータを指定する
TPDEQUEUE()の各リクエストでは、条件を満たすメッセージがすぐに利用できない場合、キュー・マネージャ(
TMQUEUE)のアクション・オブジェクトを使用できる必要があります。アクション・オブジェクトを利用できない場合、
TPDEQUEUE()リクエストは失敗します。利用できるキュー・マネージャのアクション数は、キュー・スペースの作成時または変更時に指定されます。待機中のキューからの取出しリクエストが完了すると、対応するアクション・オブジェクトは別のリクエストに使用できるようになります。
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()が完了します。
この値が設定され、
TPDEQUEUE()の呼出しが成功し、メッセージが明示的な優先度でキューに登録された場合は、その優先度が
PRIORITYに格納されます。優先度は1以上100以内の範囲内で、数値が高いほど優先度も高くなります。つまり、高い数値のメッセージが低い数値のメッセージよりも先にキューから取り出されます。
TPQNOPRIORITYが設定されている場合、優先度は使用できません。
メッセージのキューへの登録時に優先度が明示的に指定されていない場合、そのメッセージの優先度は50になります。
この値を設定し、
TPDEQUEUE()の呼出しが正常終了した場合は、メッセージ識別子が
MSGIDに格納されます。メッセージ識別子の値は、32バイト全体が意味を持ちます。
TPQNOMSGIDが設定されている場合、メッセージ識別子は使用できません。
この値を設定し、
TPDEQUEUE()の呼出しが正常終了し、メッセージが相関識別子を付けてキューに登録された場合は、相関識別子が
CORRIDに格納されます。相関識別子の値は、32バイト全体が意味を持ちます。Oracle Tuxedo /Qから渡されるメッセージに対するすべての応答は、元のメッセージの相関識別子を持ちます。
TPQNOCORRIDが設定されている場合、相関識別子は使用できません。
この値が設定され、
TPDEQUEUE()の呼出しが成功し、メッセージがサービスの配信品質と共にキューに登録された場合、
TPQUEQOS-DELIVERY-FLAGで指定されるフラグ
TPQQOSDELIVERYDEFAULTPERSIST、
TPQQOSDELIVERYPERSISTENT、または
TPQQOSDELIVERYNONPERSISTENTがサービスの配信品質を示します。
TPQNODELIVERYQOSが設定されている場合、サービスの配信品質は使用できません。
メッセージのキューへの登録時にサービスの配信品質が明示的に指定されていない場合は、ターゲット・キューのデフォルトの配信ポリシーによってメッセージの配信サービスの品質が決まります。
この値が設定され、
TPDEQUEUE()の呼出しが成功し、メッセージがサービスの応答品質と共にキューに登録された場合、
TPQUEQOS-REPLY-FLAGで指定されるフラグ
TPQQOSREPLYDEFAULTPERSIST、
TPQQOSREPLYPERSISTENT、または
TPQQOSREPLYNONPERSISTENTがサービスの配信品質を示します。
TPQNOREPLYQOSが設定されている場合、サービスの応答品質は使用できません。
メッセージがキューに入れられたときにサービスの応答品質が明示的に指定されていない場合、
REPLYQUEUEキューのデフォルトの配信ポリシーが応答に対するサービスの配信品質を指定します。デフォルトの配信ポリシーは、メッセージに対する応答がキューに登録されるときに決定されます。つまり、元のメッセージがキューに登録されてからメッセージに対する応答が登録されるまでの間に、応答キューのデフォルトの配信ポリシーが変更された場合、応答が最後に登録される時点で有効なポリシーが使用されます。
この値が設定され、
TPDEQUEUE()の呼出しが成功し、メッセージが応答キューと共にキューに登録された場合、その応答キューの名前が
REPLYQUEUEに格納されます。メッセージへの応答は、リクエスト・メッセージと同じキュー・スペース内の指定された応答キューに登録されます。
TPQNOREPLYQが設定されている場合、応答キューは使用できません。
この値が設定され、
TPDEQUEUE()の呼出しが成功し、メッセージが異常終了キューと共にキューに登録された場合、その異常終了キューの名前が
FAILUREQUEUEに格納されます。失敗メッセージは、リクエスト・メッセージと同じキュー・スペース内の指定された失敗キューに登録されます。
TPQNOFAILUREQが設定されている場合、異常終了キューは使用できません。
TPQUEDEF-RECの残りの設定は、
TPDEQUEUE()が呼び出されると、
TPQNOTOP、
TPQNOBEFOREMSGID、
TPQNOTIME_ABS、
TPQNOTIME_REL、
TPQNOEXPTIME_ABS、
TPQNOEXPTIME_REL、および
TPQNOEXPTIME_NONEに設定されます。
TPDEQUEUE()の呼出しが失敗し、
TP-STATUSに
TPEDIAGNOSTICが設定された場合、失敗の原因を示す値が
DIAGNOSTICに返されます。
DIAGNOSTICの有効な設定値には、
4-6ページの「TPQUEDEF-REC構造体」に示されている
TPENQUEUE()の値(
QMENOSPACEおよび
QMERELEASEを除く)の他に、次のものがあります。
キューから取り出せるメッセージはありません。メッセージがキュー上に存在し、別のアプリケーション・プロセスがこのメッセージをキューから読み取った可能性があることに注意してください。この場合、その別のプロセスがトランザクションをロールバックしたときに、メッセージはキューに戻されます。
メッセージ識別子または相関識別子を使用してメッセージをキューから取り出す際に、指定されたメッセージが別のトランザクションによって使用されています。それ以外の場合、現在キューにあるすべてのメッセージは、ほかのトランザクションによって使用されています。この診断は、Oracle Tuxedoリリース7.1以降のキュー・マネージャでは返されません。
フラグに
TPQWAITを設定して
TPDEQUEUE()を呼び出すと、メッセージをすぐに取り出すことができない場合、
TPDEQUEUE()が制御を呼出し側に戻す前に、
TMQUEUEサーバーは
TPDEQUEUE()リクエストに一致するメッセージがキューに到着するのを待ちます。
TMQUEUEプロセスは待機中のリクエストを無視し、他のプロセスのリクエストを処理しながら、最初のリクエストの条件が満たされるのを待ちます。
TPQGETBYMSGIDや
TPQGETBYCORRIDも指定されている場合、サーバーは指定されたメッセージ識別子や相関識別子を持つメッセージをキューから取り出せるようになるまで待ちます。このどちらのフラグも設定されていない場合、サーバーは任意のメッセージがキューに登録されるまで待ちます。呼出し側がトランザクション・モードの場合、サーバーの待機時間は、呼出し側のトランザクション・タイムアウトによって制御され、呼出し側がトランザクション・モードでない場合は、
TMQUEUEサーバーの
CLOPTパラメータに指定される
-tオプションで制御されます。
TMQUEUEサーバーは、リクエストを処理するアクション・リソースを利用できるかぎり、複数の待機中
TPDEQUEUE()リクエストを同時に処理できます。十分なアクション・リソースがキュー・スペースに対して設定されていない場合、
TPDEQUEUE()は失敗します。使用しているシステムがこれに該当する場合は、キュー・スペースに対するアクション・リソースの数を増やしてください。
キューからのメッセージの取出しで、エラー処理の最良の方法を考慮する場合、次の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()を呼び出してキューにメッセージを登録する際に、次を設定します。
|
TPQCORRID TPQREPLYQ
TPQFAILUREQ TPQMSGID
この呼出しを行う前に、
CORRID、
REPLYQUEUE、および
FAILUREQUEUEの値を設定します。呼出しから制御が戻ったら、
CORRIDを保存します。
3.
|
TPDEQUEUE()を呼び出して応答を確認する際に、 QNAMEに応答キューを指定し、次を設定します。
|
TPQCORRID TPQREPLYQ
TPQFAILUREQ TPQMSGID
TPQGETBYCORRID
この呼出しを行う前に、保存した相関識別子を使用して
CORRIDに入力します。
TPDEQUEUE()の呼出しが失敗し、
TP-STATUSに
TPEDIAGNOSTICが設定された場合、詳しい情報を
DIAGNOSTICから取得できます。エラー・コード
QMENOMSGを受信した場合、キューから取り出すことのできるメッセージがなかったことを示します。
4.
|
もう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を使用することに適している場合は、管理者に別のキューを作成してもらい、そのキューから
メッセージを取り出す独自の受信用プログラムをコーディングします。