tpdequeue()
- キューからメッセージを取り出すルーチン
#include <atmi.h>
#include <tmqentry.h>
#include <tmqreturn.h>
int tpdequeue(char *qspace, char *qname, TPQCTL *ctl, char **data, long *len, long flags)
tpdequeue()
は、キュー・スペースqspace
内のqname
で指定されるキューから、処理するメッセージを取り出します。
省略時設定では、キューの先頭のメッセージが取り出されます。キュー上のメッセージの順序は、そのキューの作成時に定義されます。アプリケーションは、ctl
パラメータでメッセージ識別子または相関識別子を指定することにより、特定のメッセージのキューからの取出しをリクエストできます。メッセージが現在利用できなかった場合にはアプリケーションはメッセージを待つということを示すために、ctl
フラグを使用することもできます。ctl
パラメータを使って、メッセージをキューから削除したりキューでのメッセージの相対位置を変更せずにメッセージを見ることができます。この後のこのパラメータについての説明を参照してください。
data
はメッセージが読み込まれるバッファに対するポインタのアドレスです。len
はそのメッセージの長さを指します。*data
は、最初にtpalloc()
によって割り当てられたバッファを指す必要があります。メッセージがtpdequeue
に渡されるバッファよりも大きい場合、バッファはメッセージが入れる大きさまで拡大されます。メッセージ・バッファのサイズに変化があるかどうかを判別するには、tpdequeue()
が発行される前の(合計の)サイズを*len
と比較します。*len
のほうが大きい場合、バッファは大きくなっています。そうでない場合は、バッファのサイズは変更されていません。なお、*data
は、バッファのサイズが大きくなったこと以外の理由でも変化する可能性があるので注意してください。終了時に*len
が0である場合は、取り出されたメッセージにはデータ部がなく、*data
も*dataが指すバッファも変更されていません。*data
またはlen
がNULLであるとエラーになります。
呼出し側がトランザクション・モードにあり、TPNOTRAN
フラグが設定されていない場合は、メッセージはトランザクション・モードでキューから取り出されます。この結果、tpdequeue()
が正常終了して呼出し側のトランザクションが正常にコミットされると、リクエストはキューから削除されます。呼出し側のトランザクションが、明示的に、またはトランザクション・タイムアウトあるいはなんらかの通信エラーの結果としてロールバックされると、メッセージはキュー上に残されます。つまり、キューからのメッセージの削除もロールバックされます。同じトランザクション内で、同じメッセージの登録と取出しを行うことはできません。
呼出し側がトランザクション・モードにないか、またはTPNOTRAN
フラグが設定されている場合は、メッセージはトランザクション・モードではキューから取り出されません。トランザクション・モードでない場合に通信エラーまたはタイムアウトが発生した場合、アプリケーションには、メッセージが正しくキューから取り出されたかどうかがわからず、メッセージが失われることがあります。
TPNOTRAN
TPNOBLOCK
tperrno
にTPEBLOCK
が設定されます。このフラグが設定されていて、ターゲットのキューが別のアプリケーションによって排他的にオープンされているなどのブロッキング条件が存在する場合には、呼出しは失敗してtperrno
にTPEDIAGNOSTIC
が設定され、TPQCTL
構造体の診断フィールドはQMESHARE
に設定されます。後者の場合、Oracle Tuxedo ATMIシステム以外のOracle製品をベースとするアプリケーションが、キューイング・サービスAPI (QSAPI)を使用した排他的な読取り/書込みのためのキューをオープンしています。
TPNOBLOCK
が設定されていない場合に、ブロッキング状態が存在すると、その状態が解消されるかタイムアウト(トランザクション・タイムアウトまたはブロッキング・タイムアウト)が発生するまで、呼出し側はブロックされます。(TPQCTL
構造体の) flags
にTPQWAIT
オプションが指定されている場合は、このブロッキング条件には、キュー自体のブロッキングは含まれません。
TPNOTIME
TPNOCHANGE
data
が指すバッファのタイプは変更されません。デフォルトでは、*data
が指すバッファとは異なるタイプのバッファが受信されると、受信側が着信バッファのタイプを識別するかぎり、*data
のバッファ・タイプは、受信されたバッファのタイプに変更されます。つまり、受信されたバッファのタイプおよびサブタイプは、*data
が指すバッファのタイプおよびサブタイプと一致する必要があります。
TPSIGRSTRT
tperrno
はTPGOTSIG
に設定されます。
tpdequeue()
が正常終了すると、アプリケーションは、ctl
データ構造体を使用してメッセージに関する追加情報を取得できます。この情報には、キューから取り出されたメッセージのメッセージ識別子、すべての応答または異常終了メッセージに付随して、発信元がメッセージと元のリクエストを結び付けることができるようにする相関識別子、メッセージが送られるサービスの品質、メッセージの応答が送られるサービスの品質、応答が要求された場合は応答キューの名前、およびメッセージをキューから取り出すときの失敗に関する情報をアプリケーションが登録できる異常終了キューの名前が含まれます。これらについて次に説明します。
マルチスレッドのアプリケーションの場合、TPINVALIDCONTEXT
状態のスレッドは、tpdequeue()
の呼出しを発行できません。
TPQCTL
構造体は、アプリケーション・プログラムが、キューからのメッセージの取出しに関連するパラメータを渡したり、取得したりするために使用します。TPQCTL
の要素flags
は、この構造体の他のどの要素が有効であるかを示すために使用されます。
tpdequeue()
への入力時には、次の要素をTPQCTL
構造体に設定できます。
long flags; /* indicates which of the values
* are set */
char msgid[32]; /* ID of message to dequeue */
char corrid[32]; /* correlation identifier of
* message to dequeue */
tpdequeue()
の入力情報を制御するflags
パラメータの有効なビットの一覧を次に示します。
TPNOFLAGS
TPQGETBYMSGID
ctl
msgid
によって指定されたメッセージ識別子を持つメッセージのエキューをリクエストします。メッセージ識別子は、事前のtpenqueue()
呼出しによって戻されます。メッセージが別のキューに移動すると、メッセージ識別子が変わることに注意してください。また、メッセージ識別子の値は32バイトすべてが意味を持つため、ctl
msgid
によって指定された値を完全に初期化する必要があります(たとえば、NULL文字で埋めるなど)。
TPQGETBYCORRID
ctl
corrid
によって指定された相関識別子を持つメッセージのデキューをリクエストします。相関識別子は、アプリケーションがtpenqueue()
でメッセージをエンキューしたときに指定されます。また、相関識別子の値は32バイト全体が意味を持つため、ctl
corrid
によって指定された値を完全に初期化する必要があります(たとえば、NULL文字で埋めるなど)。
TPQWAIT
TPQWAIT
がTPQGETBYMSGID
またはTPQGETBYCORRID
とともに設定されている場合、指定されたメッセージ識別子または相関識別子を持つメッセージがキューに存在しないときは、エラーが戻されません。かわりに、基準を満たすメッセージを取り出すことができるようになるまで、プロセスは待機します。プロセスが呼出し側のトランザクション・タイムアウトに従っている場合、またはトランザクション・モードでない場合、プロセスは、TMQUEUE
プロセスに-t
オプションで指定されたタイムアウトの影響を受けます。
tpdequeue()
は-1を返し、tperrno
をTPEDIAGNOSTIC
に設定し、TPQCTL
構造体の診断フィールドをQMESYSTEM
に設定します。 TPQWAIT
制御パラメータを指定するtpdequeue()
の各リクエストでは、条件を満たすメッセージがすぐに利用できない場合、キュー・マネージャ(TMQUEUE
)のアクション・オブジェクトを使用できる必要があります。アクション・オブジェクトが使用できない場合、tpdequeue()
リクエストは失敗します。利用できるキュー・マネージャのアクション数は、キュー・スペースの作成時または変更時に指定されます。待機中のキューからの取出しリクエストが完了すると、対応するアクション・オブジェクトは別のリクエストに使用できるようになります。
TPQPEEK
tpdequeue
()操作にTPNOTRAN
フラグが設定されていることを意味します。つまり、非破壊的なキューからの取出しはトランザクションに含まれません。トランザクション終了前のトランザクション内で、キューに登録されたメッセージまたはキューから取り出されたメッセージを読み取ることはできません。
TPQPEEK
を使用してメッセージをキューから非破壊的に取り出す場合、非破壊的な取出しリクエストをシステムが処理する少しの間、他の非ブロッキング状態のメッセージ取出し操作からそのメッセージが認識されないことがあります。たとえば、特定の選択基準(メッセージ識別子や相関識別子など)を使用してメッセージをキューから取り出す操作が、破棄せずに取出しが現在行われているメッセージを探している場合などがあります。
tpdequeue()
からの出力時には、次の要素がTPQCTL
構造体に設定されます。
long flags; /* indicates which of the values
* should be set */
long priority; /* enqueue priority */
char msgid[32]; /* ID of message dequeued */
char corrid[32]; /* correlation identifier used to
* identify the message */
long delivery_qos; /* delivery quality of service */
long reply_qos; /* reply message quality of service */
char replyqueue[16]; /* queue name for reply */
char failurequeue[16]; /* queue name for failure */
long diagnostic; /* reason for failure */
long appkey; /* application authentication client
* key */
long urcode; /* user-return code */
CLIENTID cltid; /* client identifier for originating
* client */
次は、tpdequeue()
からの出力情報を制御するflags
パラメータの有効なビットです。どのフラグ・ビットでも、tpdequeue()
の呼出し時にオンになっていると、メッセージがエンキューされたときに提供された値が、構造体の関連する要素に格納され、そのビットは設定されたままになります。値が使用できない場合、またはtpdequeue()
を呼び出したときにビットが設定されなかった場合、tpdequeue()
はフラグがオフの状態で完了します。
TPQPRIORITY
tpdequeue()
の呼出しが正常終了し、メッセージが明示的な優先度でキューに登録された場合、この優先度がctl
priority
に格納されます。優先度は1以上100以内の範囲内で、数値が高いほど優先度も高くなります。つまり、高い数値のメッセージが低い数値のメッセージよりも先にキューから取り出されます。優先度によって順序付けられていないキューの場合、値は情報にすぎません。
TPQMSGID
TPQCORRID
tpdequeue()
の呼出しが正常終了し、メッセージが相関識別子によってエンキューされた場合、この相関識別子がctl
corrid
に格納されます。相関識別子の値は、32バイト全体が意味を持ちます。Oracle Tuxedo ATMI /Qが提供するメッセージの応答には、すべて元のリクエスト・メッセージの相関識別子が付いています。
TPQDELIVERYQOS
tpdequeue()
の呼出しが成功し、メッセージがサービスの配信品質とともにキューに登録されていた場合、TPQQOSDEFAULTPERSIST
、TPQQOSPERSISTENT
、またはTPQQOSNONPERSISTENT
フラグがctl->delivery_qos
に格納されます。メッセージがキューに登録されたときに配信サービスの品質が明示的に指定されていない場合は、ターゲットとなるキューのデフォルトの配信ポリシーによってメッセージ配信の品質が決まります。
TPQREPLYQOS
tpdequeue()
の呼出しが成功し、メッセージがサービスの応答品質とともにキューに登録されていた場合、TPQQOSDEFAULTPERSIST
、TPQQOSPERSISTENT
、またはTPQQOSNONPERSISTENT
フラグがctl->reply_qos
に格納されます。メッセージがキューに登録されていたときに応答のサービス品質が明示的に指定されていない場合、ctl->replyqueue
キューのデフォルトの配信ポリシーによって、すべての応答に対する配信サービスの品質が決まります。
TPQREPLYQ
tpdequeue()
の呼出しが正常終了し、メッセージが応答キューによってエンキューされた場合、応答キューの名前がctl
replyqueue
に格納されます。メッセージへの応答は、リクエスト・メッセージと同じキュー・スペース内の指定されたキューに登録されます。
TPQFAILUREQ
tpdequeue()
の呼出しが正常終了し、メッセージが失敗キューによってエンキューされた場合、失敗キューの名前がctl
failurequeue
に格納されます。異常終了メッセージは、リクエスト・メッセージと同じキュー・スペース内の指定された異常終了キューに登録されます。
flags
パラメータの残りのビットは、tpdequeue()
が呼び出されるとクリア(0に設定)されます。これには、TPQTOP
、TPQBEFOREMSGID
、TPQTIME_ABS
、TPQTIME_REL
、TPQEXPTIME_ABS
、TPQEXPTIME_REL
、およびTPQEXPTIME_NONE
が含まれます。これらのビットは、tpenqueue()
の入力情報を制御するflags
パラメータの有効なビットです。
tpdequeue()
の呼出しが失敗してtperrno
にTPEDIAGNOSTIC
が設定された場合は、失敗の原因を示す値がctl
diagnostic
に戻されます。戻される可能性のある値は、この後の「診断」の項で定義しています。
また出力時には、tpdequeue()
の呼出しが正常に終了すると、ctl
appkey
にアプリケーション認証キーが設定され、ctl
cltid
にリクエストの発信元であるクライアントの識別子が設定され、ctl
urcode
にメッセージ登録時に設定されたユーザー戻り値が設定されます。
ctl
パラメータがNULLである場合、入力フラグはTPNOFLAGS
とみなされ、アプリケーション・プログラムは出力情報を利用できません。
異常終了すると、tpdequeue()
は -1を返し、tperrno
を設定してエラー条件を示します。
異常終了時には、tpdequeue()
はtperrno
を次のいずれかの値に設定します。(特記しないかぎり、エラーが呼出し側のトランザクションに影響を及ぼすことはありません。)
TPEINVAL
]
TPENOENT
]
qspace
を利用できないので、これにアクセスできません(関連するTuxMsgQ
サーバーは利用できません)。または、グローバル・トランザクション・テーブル(GTT)にエントリがないので、グローバル・トランザクションを開始できません。
TPEOTYPE
]
TPNOCHANGE
がflags
に設定されていますが、*data
のタイプおよびサブタイプが、サービスによって送信された応答のタイプおよびサブタイプと一致しません。いずれの場合も、*data
、その内容、および*len
はいずれも変更されません。 呼出しがトランザクション・モードで行われ、このエラーが発生すると、トランザクションは中断のみになり、メッセージはキューに残ります。
TPETIME
]
TPNOBLOCK
またはTPNOTIME
が指定されている場合は発生しません。)いずれのケースでも、*data
、その内容、*len
はいずれも変更されません。 トランザクション・タイムアウトが発生すると、1つの例外を除き、トランザクションが中断されないかぎり、会話を継続したり、新しいリクエストを送信したり、未処理の応答を受信しようとしても、TPETIME
で失敗します。その例外とは、ブロックされず、応答を期待せず、かつ呼出し側のトランザクションのかわりに送信されない(つまり、TPNOTRAN
、TPNOBLOCK
およびTPNOREPLY
を設定してtpacall()
を呼び出した場合の)リクエストです。 サービスがトランザクションの内部で失敗した場合、そのトランザクションはTX_ROLLBACK_ONLY
状態に置かれます。ほとんどの場合、この状態はタイムアウトと同じものとして扱われます。このトランザクションの以降のATMI呼出しは、TPETIME
で異常終了します(前の段落で説明した例外を除く)。
TPEBLOCK
]
TPGOTSIG
]
TPEPROTO
]
TPESYSTEM
]
TPEOS
]
TPEDIAGNOSTIC
]
次の診断値は、キューからのメッセージの取出し中に返されます。
QMEINVAL
]
QMEBADRMID
]
QMENOTOPEN
]
QMETRAN
]
TPNOTRAN
フラグを設定して呼び出したために、メッセージをキューから取り出すトランザクション開始のエラーが発生しました。この診断は、Oracle Tuxedoリリース7.1以降のキュー・マネージャからは返されません。
QMEBADMSGID
]
QMESYSTEM
]
QMEOS
]
QMEABORTED
]
QMEPROTO
]
QMEBADQUEUE
]
QMENOMSG
]
QMEINUSE
]
QMESHARE
]
qmadmin(1),
tpalloc(3c)、tpenqueue()
、 APPQ_MIB(5)
、
TMQUEUE(5)
tpenqueue()
- メッセージをキューに登録するルーチン
#include <atmi.h>
#include <tmqentry.h>
#include <tmqreturn.h>
int tpenqueue(char *qspace, char *qname, TPQCTL *ctl, char *data, long len, long flags)
tpenqueue()
は、キュー・スペースqspace
内のqname
で指定されるキューに、メッセージを格納します。キュー・スペースは、キューを集めたもので、そのうちの1つのキューがqname
でなければなりません。
メッセージがOracle Tuxedo ATMIシステムのサーバーを対象としている場合、qname
は、サーバーによって提供されるサービスの名前に一致します。システムが提供するサーバーであるTMQFORWARDPLUS
は、メッセージをキューから取り出し、キューと同じ名前のサービスを提供するサーバーにそのメッセージを転送するデフォルトのメカニズムとなります。発信元が応答を期待していた場合は、転送されたサービス・リクエストへの応答は、特に指定されている場合を除き、発信元のキューに格納されます。発信元は、後で応答メッセージをキューから取り出します。キューは、任意の2つのOracle Tuxedo ATMIシステムのプロセス間(クライアントやサーバー)における信頼性の高いメッセージ転送メカニズム用としても使用できます。この場合、キューの名前はサービス名とは一致せず、メッセージ転送のための名前に関連します。
data
がNULL以外である場合、これは事前にtpalloc()
によって割り当てられたバッファを指さなければならず、len
は、キューに登録されるバッファ内のデータの大きさを指定しなければなりません。長さを指定する必要のないタイプのバッファ(FML
フィールド化バッファなど)をdata
が指す場合、len
は無視されます。data
がNULLの場合、len
は無視され、データ部分なしでメッセージはキューに登録されます。
メッセージは、qspace
用に定義された優先度が事前のtpsprio()
の呼出しによって無効化されていないかぎり、qspace用の優先度でキューに登録されます。
呼出し側がトランザクションにあり、TPNOTRAN
フラグが設定されていない場合は、メッセージは、トランザクション・モードでエンキューされます。この結果、tpenqueue()
が正常終了して呼出し側のトランザクションが正常にコミットされると、メッセージは、トランザクションの完了後に処理されることが保証されます。呼出し側のトランザクションが、明示的に、またはトランザクション・タイムアウトあるいはなんらかの通信エラーの結果としてロールバックされると、メッセージはキューから削除されます(つまり、キューへのメッセージの登録もロールバックされます)。同じトランザクション内で同じメッセージの登録と取出しを行うことはできません。
呼出し側がトランザクション・モードにないか、またはTPNOTRAN
フラグが設定されている場合は、メッセージはトランザクション・モードではキューに登録されません。tpenqueue()
が正常終了すれば、出されたメッセージが処理されることが保証されます。トランザクション・モードでないときに通信エラーまたはタイムアウトが発生した場合、アプリケーションには、メッセージが正しくキューに格納されたかどうかがわかりません。
メッセージが処理される順序は、この後説明するように、ctl
データ構造体を介してアプリケーションによって制御されます。デフォルトのキューの順序は、キューの作成時に設定されます。
TPNOTRAN
TPNOBLOCK
tperrno
にTPEBLOCK
が設定されます。このフラグが設定されていて、ターゲットのキューが別のアプリケーションによって排他的にオープンされているなどのブロッキング条件が存在する場合には、呼出しは失敗してtperrno
にTPEDIAGNOSTIC
が設定され、TPQCTL
構造体の診断フィールドはQMESHARE
に設定されます。後者の場合、Oracle Tuxedo ATMIシステム以外のOracle製品をベースとするアプリケーションが、キューイング・サービスAPI (QSAPI)を使った排他的な読み書きのためのキューをオープンしています。
TPNOBLOCK
が設定されていない場合に、ブロッキング状態が存在すると、その状態が解消されるかタイムアウト(トランザクション・タイムアウトまたはブロッキング・タイムアウト)が発生するまで、呼出し側はブロックされます。タイムアウトが発生すると、呼出しは異常終了し、tperrno
はTPETIME
に設定されます。
TPNOTIME
TPSIGRSTRT
TPSIGRSTRT
が指定されておらず、システム・コールがシグナルによって中断された場合、tpenqueue()
は異常終了し、tperrno
にTPGOTSIG
が設定されます。
キューへのメッセージ登録に関する追加情報は、ctl
データ構造体を介して指定できます。この情報には、デフォルトのキューの順序付けをオーバーライドしてキューの先頭または登録済のメッセージの前にメッセージを登録するための値、キューからメッセージを取り出すまでの絶対時間または相対時間、メッセージが期限切れになりキューから削除される絶対時間または相対時間、メッセージ配信サービスの品質、メッセージが応答する際のサービス品質、メッセージとそのメッセージに関連付けられた応答または失敗メッセージを結び付けるときに役立つ相関識別子、応答を登録するキューの名前、およびすべての失敗メッセージを登録するキューの名前が含まれます。
マルチスレッドのアプリケーションの場合、TPINVALIDCONTEXT
状態のスレッドはtpenqueue()
を呼び出すことはできません。
TPQCTL
構造体は、アプリケーション・プログラムが、キューへのメッセージの登録に関連するパラメータを渡したり、取得したりする際に使用されます。TPQCTL
の要素flags
は、この構造体の他のどの要素が有効であるかを示すために使用されます。
tpenqueue()
への入力時には、次の要素をTPQCTL
構造体に設定できます。
long flags; /* indicates which of the values
* are set */
long deq_time; /* absolute/relative for dequeuing */
long priority; /* enqueue priority */
long exp_time /* expiration time */
long delivery_qos /* delivery quality of service */
long reply_qos /* reply quality of service */
long urcode; /* user-return code */
char msgid[32]; /* ID of message before which to queue
* request */
char corrid[32]; /* correlation identifier used to
* identify the msg */
char replyqueue[16]; /* queue name for reply message */
char failurequeue[16]; /* queue name for failure message */
tpenqueue()
の入力情報を制御するflags
パラメータの有効なビットの一覧を次に示します。
TPNOFLAGS
TPQTOP
TPQTOP
とTPQBEFOREMSGID
は、相互に排他的なフラグです。
TPQBEFOREMSGID
ctl
msgid
によって識別されるメッセージの前に登録されます。このリクエストは、順序付けを無効にするようにキューが設定されているかどうかによって、使用できない場合があります。TPQTOP
とTPQBEFOREMSGID
は、相互に排他的なフラグです。また、メッセージ識別子の値は32バイト全体が意味を持つため、ctl
msgid
によって指定された値を完全に初期化する必要があります(たとえば、NULL文字で埋めるなど)。
TPQTIME_ABS
ctl
deq_time
によって指定された時間の後で使用可能になります。deq_time
は、time
(2)、mktime(3)
、またはgp_mktime(3c)によって生成された絶対時間値、つまり協定世界時(UTC)の1970年1月1日00:00:00から経過した秒数です。TPQTIME_ABS
とTPQTIME_REL
は、相互に排他的なフラグです。絶対時間は、キュー・マネージャ・プロセスが常駐するマシンの時計によって決定されます。
TPQTIME_REL
ctl
deq_time
は、キューの登録が完了した後、出されたリクエストが処理されるまでの遅延秒数を指定します。TPQTIME_ABS
とTPQTIME_REL
は、相互に排他的なフラグです。
TPQPRIORITY
ctl
priority
に格納されます。優先度は、1以上100以下の範囲でなければなりません。数値が高いほど優先度も高くなり、高い数値のメッセージが低い数値のメッセージより先にキューから取り出されます。優先度によって順序付けられていないキューでは、この値は参考として使用されます。
TPQCORRID
ctl
corrid
で指定された相関識別子の値は、メッセージがtpdequeue()
によってデキューされるときに使用できます。この識別子は、キューに登録されるすべての応答メッセージまたは異常終了メッセージに付加されるので、アプリケーションは応答を特定のリクエストに結び付けることができます。また、相関識別子の値は32バイト全体が意味を持つため、ctl
corrid
で指定された値を完全に初期化する必要があります(たとえば、NULL文字で埋めるなど)。
TPQREPLYQ
ctl
replyqueue
で指定された応答キューは、待機メッセージに関連付けられます。メッセージに対する応答はすべて、リクエスト・メッセージと同じキュー・スペース内の指定されたキューに登録されます。この文字列は、NULLで終了しなければなりません(最大15文字)。
TPQFAILUREQ
ctl
failurequeue
で指定された失敗キューは、待機メッセージに関連付けられます。(1)キューに登録されたメッセージがTMQFORWARD()
によって処理され、(2) TMQFORWARD
が-d
オプションで開始され、さらに(3)サービスが失敗してNULL以外の応答を戻す場合は、その応答と関連するtpurcode
によって構成される失敗メッセージが、元のリクエスト・メッセージと同じキュー・スペース内で指定されたキューに登録されます。この文字列はNULLで終了し、15文字以下であることが必要です。
TPQDELIVERYQOS
、TPQREPLYQOS
TPQDELIVERYQOS
フラグが設定されていると、ctl->delivery_qos
で指定されたフラグにより、メッセージの配信サービスの品質が制御されます。その場合、相互に排他的な3つのフラグTPQQOSDEFAULTPERSIST
、TPQQOSPERSISTENT
、TPQQOSNONPERSISTENT
のいずれかをctl->delivery_qos
に設定しなければなりません。TPQDELIVERYQOS
フラグが設定されていない場合、ターゲットのキューのデフォルトの配信ポリシーがメッセージに対するサービスの配信品質を指定します。
TPQREPLYQOS
フラグが設定されていると、ctl->reply_qos
で指定されるフラグが、メッセージの応答に対するサービスの品質を制御します。その場合、相互に排他的な3つのフラグTPQQOSDEFAULTPERSIST
、TPQQOSPERSISTENT
、TPQQOSNONPERSISTENT
のいずれかをctl->reply_qos
に設定しなければなりません。TPQREPLYQOS
フラグは、TMQFORWARD
によって処理されるメッセージから応答が返されるときに使用されます。サービスを呼び出すときにTMQFORWARD
を使用しないアプリケーションでは、自身の応答メカニズムのヒントとしてTPQREPLYQOS
フラグを使用できます。 TPQREPLYQOSが設定されていない場合、ctl->replyqueue
キューのデフォルトの配信ポリシーが応答に対するサービスの配信品質を指定します。デフォルトの配信ポリシーは、メッセージに対する応答がキューに登録されるときに決定される点に注意してください。つまり、元のメッセージがキューに登録されてからメッセージに対する応答が登録されるまでの間に、応答キューのデフォルトの配信ポリシーが変更された場合、応答が最後に登録される時点で有効なポリシーが使用されます。 次は、ctl->delivery_qos
とctl->reply_qos
の有効なフラグです。
TPQEXPTIME_ABS
ctl->exp_time
に格納された値で示されます。ctl->exp_time
の値は、time(2)
、mktime(3C)
、またはgp_mktime(3c)によって生成された絶対時間、つまり協定世界時(UTC)の1970年1月1日00:00:00から経過した秒数に設定されなければなりません。 キューへの登録操作の時間より早い絶対時間が指定されると、操作は成功しますが、メッセージはしきい値の計算の対象になりません。有効期限の時間がメッセージの使用可能時間より前の場合、使用可能時間が有効期限の切れる時間より前になるようにいずれかの時間を変更しないかぎり、メッセージをキューから取り出すことはできません。また、これらのメッセージがキューからの取出しの対象になったことがなくても、有効期限が切れるとキューから削除されます。トランザクション内でメッセージの期限が切れた場合、それによってトランザクションが異常終了することはありません。トランザクション内でキューへの登録、またはキューからの取出し中に有効期限が切れたメッセージは、トランザクションが終了した時点でキューから削除されます。メッセージの有効期限が切れたことの通知は行われません。 TPQEXPTIME_ABS
、TPQEXPTIME_REL
、およびTPQEXPTIME_NONE
は、相互に排他的なフラグです。この3つのどのフラグも設定されていない場合、ターゲットのキューに対応しているデフォルトの有効期限の時間がメッセージに適用されます。
TPQEXPTIME_REL
ctl->exp_time
に格納された値で示されます。
TPQEXPTIME_ABS
、TPQEXPTIME_REL
、およびTPQEXPTIME_NONE
は、相互に排他的なフラグです。この3つのどのフラグも設定されていない場合、ターゲットのキューに対応しているデフォルトの有効期限の時間がメッセージに適用されます。
TPQEXPTIME_NONE
TPQEXPTIME_ABS
、TPQEXPTIME_REL
、およびTPQEXPTIME_NONE
は、相互に排他的なフラグです。この3つのどのフラグも設定されていない場合、ターゲットのキューに対応しているデフォルトの有効期限の時間がメッセージに適用されます。
また、TPQCTL
の要素urcode
にユーザー戻り値を設定することができます。この値は、メッセージをキューから取り出すアプリケーションに返されます。
tpenqueue()
からの出力時には、次の要素がTPQCTL
構造体に設定されます。
long flags; /* indicates which of the values
* are set */
char msgid[32]; /* ID of enqueued message */
long diagnostic; /* indicates reason for failure */
tpenqueue()
からの出力情報を制御するflags
パラメータの有効なビットの一覧を次に示します。tpenqueue()
の呼出し時にこのフラグがオンになっていると、/QサーバーTMQUEUE(5)
は、構造体の対応する要素にメッセージ識別子を挿入します。tpenqueue()
の呼出し時にこのフラグ・ビットをオフにしていると、TMQUEUE()
によって構造体の関連要素にメッセージ識別子は設定されません。
TPQMSGID
tpenqueue()
の呼出しが正常終了した場合、メッセージ識別子がctl
msgid
に格納されます。メッセージ識別子の値は32バイト全体が意味を持つため、ctl
msgid
に格納される値は完全に初期化されます(たとえば、NULL文字で埋めるなど)。初期化に使用される実際の埋め文字は、Oracle Tuxedo ATMI /Qコンポーネントのリリースによって異なります。
制御構造体の残りのメンバーは、tpenqueue()
への入力に使用されません。
tpenqueue()
の呼出しが失敗してtperrno
にTPEDIAGNOSTIC
が設定された場合は、失敗の原因を示す値がctl
diagnostic
に戻されます。戻される可能性のある値は、この後の「診断」の項で定義しています。
このパラメータがNULLである場合、入力フラグは、TPNOFLAGS
とみなされ、アプリケーション・プログラムは出力情報を利用できません。
異常終了すると、tpenqueue()
は -1を返し、tperrno
を設定してエラー条件を示します。エラーでないときは、メッセージは、tpenqueue()
の終了時に正しくキューに登録されます。
異常終了時には、tpenqueue()
はtperrno
を次のいずれかの値に設定します。(特記しないかぎり、エラーが呼出し側のトランザクションに影響を及ぼすことはありません。)
TPEINVAL
]
TPENOENT
]
qspace
を利用できないので、これにアクセスできません(関連するTMQUEUE(5)
サーバーは利用できません)。または、グローバル・トランザクション表(GTT)にエントリがないので、グローバル・トランザクションを開始できません。
TPETIME
]
TPNOBLOCK
またはTPNOTIME
が指定されている場合は発生しません。) トランザクション・タイムアウトが発生した場合、トランザクションが中断されないかぎり、新しいリクエストの送信や未処理の応答の受信はできず、TPETIME
が発生します。その例外とは、ブロックされず、応答を期待せず、かつ呼出し側のトランザクションのかわりに送信されない(つまり、TPNOTRAN
、TPNOBLOCK
およびTPNOREPLY
を設定してtpacall()
を呼び出した場合の)リクエストです。 サービスがトランザクション内部で失敗すると、そのトランザクションはTX_ROLLBACK_ONLY
状態になります。ほとんどの場合、この状態はタイムアウトと同じものとして扱われます。このトランザクションの以降のATMI呼出しは、TPETIME
で異常終了します(前の段落で説明した例外を除く)。
TPEBLOCK
]
TPGOTSIG
]
TPEPROTO
]
TPESYSTEM
]
TPEOS
]
TPEDIAGNOSTIC
]
QMEINVAL
]
QMEBADRMID
]
QMENOTOPEN
]
QMETRAN
]
TPNOTRAN
フラグを設定して呼び出したときに、メッセージをキューに登録するトランザクションを開始してエラーが発生しました。この診断は、Oracle Tuxedoリリース7.1以降のキュー・マネージャからは返されません。
QMEBADMSGID
]
QMESYSTEM
]
QMEOS
]
QMEABORTED
]
QMEPROTO
]
QMEBADQUEUE
]
QMENOSPACE
]
QMENOSPACE
が返されます。(1)キュー・スペースに割り当てられたディスク容量(永続的)、(2)キュー・スペースに割り当てられたメモリー容量(非永続的)、(3)同時にアクティブ状態になるトランザクションの最大数(キュー・スペースで許容される数であることが必要です)、(4)キュー・スペースに一度に入れることができる最大メッセージ数、(5)キューイング・サービス・コンポーネントが処理できる並列アクションの最大数、または(6)キューイング・サービス・コンポーネントを同時に使用できる認証されたユーザーの最大数。
QMERELEASE
]
QMESHARE
]
qmadmin(1)、gp_mktime(3c)、tpacall(3c)、tpalloc(3c)、tpdequeue()
、tpinit(3c)、tpsprio(3c)、APPQ_MIB(5)、TMQFORWARD(5)、TMQUEUE(5)
tpqattach()
- アプリケーション・プログラムをメッセージ・キューにアタッチすることにより、OTMQのメッセージ・キュー・スペースに接続します。
#include <atmi.h>
#include <tmqentry.h>
#include <tmqreturn.h>
int tpqattach (qspace, queue, ctl, qattachctl, flags)
メッセージ・キュー・スペースは、システム、共有グローバル・メモリー・セクションおよびファイルに存在するメッセージ・キューのコレクションで、同じサーバー・プロセスによって処理されます。OTMQのメッセージ・キューは、メッセージが格納および取得されるメモリーまたはディスクの領域です。OTMQ環境の構成方法については、ご使用のプラットフォーム用のインストレーションおよび構成ガイドを参照してください。
OTMQメッセージを受信するには、少なくとも1つのメッセージ・キューにアタッチする必要があります。アプリケーションは、tpqattach
関数により、次の手順でアタッチできます。
tmqadmin
のcreatequeue
コマンドを実行して作成されている必要があります。名前によるアタッチにより、特定のキューにアタッチし、キューにメッセージを送信し、そのキューに送信されたメッセージを取得できます。 tmqadmin
のcreatequeue
コマンドを実行して作成されている必要があります。名前のエイリアスによるアタッチにより、特定のキューにアタッチし、キューにメッセージを送信し、そのキューに送信されたメッセージを取得できます。さらに、名前のエイリアスによるアタッチでは、キュー名のエイリアスが変更になってもコードの変更や再コンパイルが不要です。このため、名前のエイリアスによるアタッチは、OTMQの環境構成の変更からアプリケーションを保護します。 アプリケーションでは、プライマリまたはセカンダリのアタッチメントを指定できます。すべてのアプリケーションにはプライマリ・キューがあります。それに加え、1つ以上のセカンダリ・キューにアタッチできます。プライマリ・キューは、キューの作成コマンドでセカンダリ・キューの所有者として構成できます。セカンダリ・キューの所有者であるプライマリ・キューにアタッチすると、プライマリ・キューにアタッチされるのと同時に、そのアプリケーションは自動的にセカンダリ・キューにもアタッチされます。
それに加え、複数リソースのキューにアタッチできます。複数リソースのキューは、多くのアプリケーションからの読取りが可能で、グループ定義の一部として構成されます。
表1-2に、tpqattach()
がサポートする引数を示します。
qspace
queue
attach_mode
引数でキュー名またはキューのエイリアスによるアタッチメントが指定された場合に、アプリケーションにアタッチする永続キューの名前を指定します。キュー名は、途中に空白を含まない英数字の文字列で、特殊文字としてアンダースコア(_)
、ハイフン(-)
およびドル記号($)
も使用できます。最大長は127です。
tmqadmin
のキューの作成コマンドで入力したキュー名と一致する必要があります。キュー名の例としては、QUEUE_1
、high-priority、My$Queue
などがあります。
ctl
TPQCTL構造体は、アプリケーション・プログラムで、キューへのメッセージの登録に関連するパラメータを渡したり、取得したりする際に使用します。TPQCTLのflags要素は、この構造体の他のどの要素が有効であるかを示すために使用されます。
tpenqplus()
への入力として、リスト1-1に示す要素がTPQCTL構造体に設定できます。
long flags; /* indicates which of the values are set */
long deq_time; /* absolute/relative time for dequeuing */
long priority; /* enqueue priority */
long diagnostic; /* indicates reason for failure */
char msgid[TMMSGIDLEN]; /* id of message before which to queue */
char corrid[TMCORRIDLEN];/* correlation id used to identify message */
char replyqueue[TMQNAMELEN+1]; /* queue name for reply message */
char failurequeue[TMQNAMELEN+1];/* queue name for failure message */
CLIENTID cltid; /* client identifier for originating client */
long urcode; /* application user-return code */
long appkey; /* application authentication client key */
long delivery_qos; /* delivery quality of service */
long reply_qos; /* reply message quality of service */
long exp_time; /* expiration time */
/* new members for TMQPlus */
long block; /* specify block mode: WF, AK, NN */
long DIP; /* specify the delivery interesting point:MEM, SAF, DQF, DEQ, ACK, CONF */
long uma; /* undelivered message action */
long msg_class; /* message class */
long msg_type; /* message type */
PSB status_block; /* message delivery control point and UMA status block */
long redeliver_count; /* the max count which the message can be redelivered */
long seq_number[2]; /* message seq number, which is decided in client side to decrease the TMQ load */
long timeout; /* timeout value for block enq/deq operation */
char src_qspace[TMQSNAMELEN+1]; /* the source QSpace name. */
char src_qname[TMQNAMELEN+1]; /* the source queue name. */
char tgt_qspace[TMQSNAMELEN+1]; /* the source QSpace name. */
char tgt_qname[TMQNAMELEN+1]; /* the source queue name. */
char orig_src_qspace[TMQSNAMELEN+1];/* the original source QSpace name. */
char orig_src_qname[TMQNAMELEN+1]; /* the original source queue name. */
char orig_tgt_qspace[TMQSNAMELEN+1];/* the original target QSpace name. */
char orig_tgt_qname[TMQNAMELEN+1]; /* the original target queue name. */
char hops; /* net hops */
long opcode;
long filter_idx;
long user_tag;
long geta_idx; /* index of pending pams_get_msga requests */
long endian;
long receipt_msg_type; /*used for uma message*/
Qattachctl
これは、アプリケーション・プログラムで、キューへのアタッチに関連するパラメータを渡すために使用します。リスト1-2に示す要素がQ_ATTACH_CTL
構造体に設定できます。
TM32I attachmode; /* Supplies the mode for attaching the application to a message queue.*/
TM32I qtype; /* Supplies the queue type for the attachment. */
TM32I * namespace_list; /* Supplies a list of name tables to search when the attach_mode argument. */
TM32I namespace_list_len; /* Supplies the number of entries in the name_space_list argument. */
long timeout; /* The number of OTMQ time units (1 second intervals) to allow for the attach to complete. */
char group[MAXTIDENT+1]; /* specific group name to attach*/
Q_ATTACH_CTL
構造体のグループ・フィールドgroup[MAXTIDENT+1]
を使用して、アタッチする特定のグループを指定します。指定されたグループが見つからない場合は、現在のリクエストが失敗するだけでなく、後続のすべてのエンキュー/デキュー・リクエスト(指定されたグループに送信されるリクエスト)も失敗します。
Q_ATTACH_CTL qattachctl;
memset(&qattachctl, 0x0, sizeof(qattachctl));
qattachctl.attachmode = OTMQ_ATTACH_BY_NAME;
...
strcpy(qattachctl.group, "group1");
tpqattach(q_space, q_name, &ctl, &qattachctl, flags);
注: | Q_ATTACH_CTL 構造を変更してグループ名を追加した場合、OTMQクライアントは新しいOTMQライブラリを使用して再コンパイルおよび再リンクする必要があります。 |
Flags
tperrno
にTPEBLOCK
が設定されます。このフラグが設定されていて、ターゲットのキューが別のアプリケーションによって排他的にオープンされているなどのブロッキング条件が存在する場合には、呼出しは異常終了し、tperrno
にTPEDIAGNOSTIC
が設定され、TPQCTL構造体の診断フィールドはQMESHARE
に設定されます。後者の場合、Oracle Tuxedo ATMIシステム以外のOracle製品をベースとするアプリケーションが、キューイング・サービスAPI (QSAPI)を使った排他的な読み書きのためのキューをオープンしています。
TPNOBLOCK
が設定されていない場合に、ブロッキング状態が存在すると、その状態が解消されるかタイムアウト(トランザクション・タイムアウトまたはブロッキング・タイムアウト)が発生するまで、呼出し側はブロックされます。タイムアウトが発生すると、呼出しは異常終了し、tperrno
はTPETIME
に設定されます。
TPSIGRSTRT
が指定されておらず、システム・コールがシグナルによって中断された場合、tpenqueue()
は異常終了し、tperrno
にTPGOTSIG
が設定されます。
[TPEINVAL]
[TPENOENT]
[TPETIME]
[TPEBLOCK]
[TPESYSTEM]
[TPEOS]
[TPEDIAGNOSTIC]
[QMEINVAL]
[QMESYSTEM]
[QMEOS]
[QMEABORTED]
[QMEBADQUEUE]
tpqdetach()
- 選択したメッセージ・キューまたはそのアプリケーションのすべてのメッセージ・キューを、メッセージのキューイング・スペースからデタッチします。
#include <atmi.h>
#include <tmqentry.h>
#include <tmqreturn.h>
int tpqdetach ( qspace, queue, detach_opt_list, detach_opt_len, msg_flushed , flags)
選択したメッセージ・キューまたはそのアプリケーションのすべてのメッセージ・キューを、メッセージのキューイング・スペースからデタッチします。アプリケーションがそのプライマリ・キューからデタッチすると、この関数によって、自動的にそのプライマリ・キューに定義されているすべてのセカンダリ・キューへのアタッチがデタッチされます。最後のメッセージ・キューがデタッチされると、アプリケーションは、自動的にOTMQメッセージをキューイングするqspaceからデタッチされます。
リカバリ可能メッセージングに暗黙的な確認を使用している場合、次に示す処理に先だって、最後のメッセージが確認済であることを保証する必要があります。
デタッチや終了の前に、確実に最後のメッセージを確認済にしないと、そのキューが再度アタッチされたときにメッセージが再配信されます。確実に確認を行う最も簡単な方法は、最後に受信したメッセージのPSBの配信ステータスを保存しておき、要求された確認ステータスをチェックして、そのメッセージが確認済になった後で終了することです。
表1-3に、tpqdetach()
がサポートする引数を示します。
tpqcancelget
関数を使用して、無効化された選択マスクを取り消す必要があります。
異常終了すると、tpqdetach()
は-1を返し、tperrno
を設定してエラーの状況を示します。そうでない場合は、tpqdetach()
から戻ったとき、キューは正常にデタッチされています。
tpqbind()
- 実行時に、キュー名をキューの参照に動的に関連付けます。
#include <atmi.h>
#include <tmqentry.h>
#include <tmqreturn.h>
int tpqbind (qspace , pNameCtl , scope, timeout);
実行時に、キュー名をキューの参照に動的に関連付けます。これにより、サーバー・アプリケーションで実行時に動的にキューのエイリアスをサービスに登録できます。これによりエンド・ユーザーは、通常のホスト・コンピュータが停止しても、サービスが別のホスト・コンピュータで提供されていることを意識せずにサービスにアクセスできます。tpqbind()
を使用するには、まずtpqattach()
を呼び出す必要があります。
表1-4に、tpqbind()
がサポートする引数を示します。
qspace
pNameCtl
TM32I nOwnerPid; /* client pid */
TM32I * namespace_list; /* for using pams interface */
TM32I namespace_list_len; /* for using pams interface */} Q_NAME_CTL;
pGroup
およびpQueue
が指定されている場合、この関数はそれをpName
にバインドします。0が指定された場合、この関数はpName
をそのキュー名からアンバインドします。呼出し元アプリケーションは、pNameが再びゼロに設定されるまでpNameにバインドされています。
OTMQ_TBL_GRP
とOTMQ_TBL_PROC
の両方を指定します。これにより、グループ・キャッシュを検索する前にプロセス・キャッシュがチェックされます。
OTMQ_TBL_BUS、OTMQ_TBL_GRP
およびOTMQ_TBL_PROC
を指定します。これにより、プロセス・キャッシュがチェックされます。そして、グローバル・ネームスペースを検索する前にグループ・キャッシュがチェックされます。
OTMQ_TBL_BUS
のかわりにOTMQ_TBL_BUS_LOW
を指定する点に注意してください。
OTMQ_TBL_BUS
のかわりにOTMQ_TBL_BUS_MEDIUM
を指定します。
name_space_list
引数のエントリの数を指定します。name_space_list_len
引数がゼロの場合、デフォルトとして、name_space_list
引数にOTMQ_TBL_GRP
を使用します。
namespace_list
引数は、scopeがNULLの場合、namespace_list
もNULLに指定することはできず、scopeに値を指定した場合、namespace_list
は無効になります。
BLOCKTIME
プロパティが使用されます(UBBCONFIGの*SERVICES
セクションで構成されています)。サービス全体のBLOCKTIME
が構成されていない場合、UBBCONFIGの*RESOURCES
セクションで指定されているシステム全体のBLOCKTIMEが使用されます(デフォルトは約60秒)。
異常終了すると、tpqbind()
は-1を返し、tperrno
を設定してエラーの状況を示します。そうでない場合は、tpqbind()
から戻ったとき、キューのエイリアスは正常にバインドされています。
tpqlocate()
- 指定されたキュー名またはキューのエイリアスに対応するキュー名を探します。
#include <atmi.h>
#include <tmqentry.h>
#include <tmqreturn.h>int tpqlocate (qspace, pNameCtl, req_id, resp_q, scope, wait_mode, timeout )
指定されたキュー名またはキューのエイリアスに対応するキュー名を探します。デフォルトでは、この関数はキュー名が戻されるまで待機します。tpqlocate()
を使用するには、まずtpqattach()
を呼び出す必要があります。
表1-5に、tpqlocate()
がサポートする引数を示します。
typedef struct {
char pName[TMQALIASLEN+1];
char pGroup[TMQSNAMELEN+1];
char pQueue[TMQNAMELEN+1];
TM32I nFlags;
TM32I nType; /* L/G */
TM32I type; /* client type */
TM32I nOwnerPid; /* client pid */
CLIENTID cltid;
TM32I * namespace_list; /* for using pams interface */
TM32I namespace_list_len; /* for using pams interface */
} Q_NAME_CTL;
OTMQ_TBL_PROC
の両方を指定します。これにより、qspaceキャッシュを検索する前にプロセス・キャッシュがチェックされます。
OTMQ_TBL_BUS
、OTMQ_TBL_GRP
およびOTMQ_TBL_PROC
を指定します。これにより、プロセス・キャッシュがチェックされます。そして、グローバル・ネームスペースを検索する前にqspaceキャッシュがチェックされます。
OTMQ_TBL_BUS
のかわりにOTMQ_TBL_BUS_MEDIUM
を指定します。
name_space_list
引数のエントリの数を指定します。引数のname_space_list_len
がゼロの場合、デフォルトとして、name_space_list
引数にはOTMQ_TBL_GRP
を使用します。
name_space_list
引数もまたキャッシュ・アクセスを制御し、ローカル・キューの参照またはキュー名をルックアップするには、OTMQ_TBL_GRP
とOTMQ_TBL_PROC
の両方を指定します。これにより、グループ・キャッシュを検索する前にプロセス・キャッシュがチェックされます。 グローバル・キューの参照をルックアップするには、OTMQ_TBL_BUS
(あるいは、OTMQ_TBL_BUS_LOW
またはOTMQ_TBL_BUS_MEDIUM
)、OTMQ_TBL_GRP
およびOTMQ_TBL_PROC
を指定します。これにより、プロセス・キャッシュがチェックされます。そして、グローバル・ネームスペースを検索する前にグループ・キャッシュがチェックされます。 マスター・データベースを検索する前に、グローバル・ネームスペース内のすべてのキャッシュをルックアップするには、OTMQ_TBL_BUS
のかわりにOTMQ_TBL_BUS_LOW
を指定する点に注意してください。 マスター・データベースを検索する前に、速度は遅くても最新のグローバル・ネームスペース内のキャッシュをルックアップするときにのみ、OTMQ_TBL_BUS
のかわりにOTMQ_TBL_BUS_MEDIUM
を指定します。 name_space_list_len
: name_space_list
引数のエントリの数を指定します。引数のname_space_list_len
がゼロの場合、デフォルトとして、name_space_list
引数にはOTMQ_TBL_GRP
を使用します。
NAME_SCOPE_P
: スコープはプロセス NAME_SCOPE_L
: スコープはローカル NAME_SCOPE_G
: スコープはグローバル。 TPのAPIのscope
およびnamespace_list
引数は、scopeがNULLの場合、namespace_list
もNULLに指定することはできず、scopeに値を指定した場合、namespace_list
は無効になります。
BLOCKTIME
プロパティが使用されます(UBBCONFIGの*SERVICES
セクションで構成されています)。サービス全体のBLOCKTIME
が構成されていない場合、UBBCONFIGの*RESOURCES
セクションで指定されているシステム全体のBLOCKTIME
が使用されます(デフォルトは約60秒)。
異常終了すると、tpqlocate()
は-1を返し、tperrno
を設定してエラーの状況を示します。そうでない場合は、tpqlocate()
から戻ったとき、キューは正常に検出されています。
[TPEINVAL]
[TPENOENT]
[TPETIME]
[TPEPROTO]
[TPESYSTEM]
[TPEOS]
tpenqplus()
- 指定されたキュー名またはキューのエイリアスに対応するキュー名を探します。
#include <atmi.h>
#include <tmqentry.h>
#include <tmqreturn.h>
int tpenqplus (qspace, qname, ctl, data, len, flags)
標準のOTMQ配信モードを使用して、メッセージをターゲットqspaceのターゲット・キューに送信します。
TPQCTL構造体のblockおよびDIP引数は、システム、プロセスまたはネットワーク障害時のメッセージ配信の保証に使用できます。リカバリ可能メッセージは、受信側プログラムのターゲット・キューに配信できるまで、メッセージ・リカバリ・システムによってディスクに格納されています。リカバリ可能メッセージを送信するときは、メッセージ・リカバリがメッセージを格納できなかった場合のため、TPQCTL構造体のuma引数を指定する必要があります。また、操作の戻りステータスを受信するため、TPQCTL構造体のPSB引数も指定する必要があります。
オプションのtimeout引数により、関数がタイムアウトするまでの、送信操作完了のための最大時間を設定できます。オプションのTPQCTL構造体のreplyqueue引数により、レスポンスを送信側プログラムのプライマリ・キューに送るかわりに、レスポンス・メッセージを受信するための代替キューを指定できます。同期モードで、応答キューからのレスポンス・メッセージの受信に失敗すると、tpenqplus()
でエラーが戻されますが、メッセージはターゲット・キューに正常に送信されている可能性はあります。
OTMQの機能を使用するには、tpenqplus
を呼び出す前にtpqattach
を呼び出す必要があります。tpenqplusの
qspace引数は、tpqattach
のqspace引数と同じである必要があります。
呼出し側がトランザクションにあり、TPNOTRAN
フラグが設定されていない場合は、メッセージは、トランザクション・モードでエンキューされます。この結果、tpenqplus()
が正常終了してコール元のトランザクションが正常にコミットされると、メッセージは、トランザクションの完了後に処理されることが保証されます。コール元のトランザクションが、明示的に、またはトランザクション・タイムアウトあるいはなんらかの通信エラーの結果としてロールバックされると、メッセージはキューから削除されます(つまり、キューへのメッセージの登録もロールバックされます)。同じトランザクション内で同じメッセージの登録と取出しを行うことはできません。
呼出し側がトランザクション・モードにないか、またはTPNOTRAN
フラグが設定されている場合は、メッセージはトランザクション・モードではキューに登録されません。tpenqplus()
が正常終了した後は、サブミットされたメッセージがキューに登録されたことが保証されます。トランザクション・モードでないときに通信エラーまたはタイムアウトが発生した場合、アプリケーションには、メッセージが正しくキューに格納されたかどうかがわかりません。
tpenqplus()
を使用するには、まずtpqattach()
を呼び出す必要があります。
表1-6に、tpenqplus()
がサポートする引数を示します。
qspace
qname
制御パラメータ
MSG_CLAS_
で始まります。クラス・シンボルの定義の詳細は、tmqsym.hインクルード・ファイルを参照してください。UNIXおよびNTシステムでは、tmqsym.hインクルード・ファイルは編集できません。アプリケーションで使用するタイプおよびクラスのシンボルを定義するインクルード・ファイルを作成する必要があります。
msg_type
引数の値にシンボリック名が使用できます。シンボリックなタイプ名はMSG_TYPE_
で始まります。タイプ・シンボルの定義の詳細は、tmqsym.h
インクルード・ファイルを参照してください。
tpqconfirmmsg
関数を使用して明示的に確認された。ACKは、受信側アプリケーションによる2番目のtpdeqplus
の呼出しの後に送信される暗黙的な確認応答である場合もあります。
OTMQ_DEL_WF
およびOTMQ_DIP_ACK
を設定した場合、ACKメッセージはtpenqplus
で読み取り、クライアントはACKメッセージを読み取るために別のAPIを呼び出す必要はありません。
tpenqplus
関数がメッセージが届くまで待機する時間の最大値を指定します。メッセージが届く前にタイムアウトが発生した場合、ステータス・コードOTMQ__TIMEOUT
が戻されます。timeoutの値に0を指定すると、タイムアウトはデフォルト値の30秒に設定されます。
psb
引数は、リカバリ可能メッセージの送受信時に使用されます。PSB構造体には、次のリスト1-4に示すようなメッセージ・リカバリ・システムからのステータス情報が格納され、メッセージの送受信の後にチェックできます。
Listing 1-3 PSB Structure
struct psb_t {
long type_of_psb; /* PSB type */
long del_psb_status; /* The completion status of the function. It contains the status from TuxMsgQ. It can also contain a value of TPSUCCESS when the message is not sent recoverably. */
long uma_psb_status; /* The completion status of the undeliverable message action (UMA). The PSB UMA status indicates if the UMA was not executed or applicable. */
long psb_reserved[6]; /* reserved filed */
};
typedef struct psb_t PSB;
Note: this structure is already defined at atmi.h.
q_name
を指定します。送信側プログラムでは、レスポンス・メッセージを受信するため、replyqueue
引数に指定したキューにアタッチする必要があります。replyqueue
を使用するには、フラグにTPQREPLYQ
を指定する必要があります。
tpalloc()
によって割り当てられたバッファを指定し、lenには、キューに登録されるバッファ内のデータの長さを指定する必要があります。長さを指定する必要のないタイプのバッファ(FMLフィールド化バッファなど)をdataが指す場合、lenは無視されます。dataがNULLの場合、lenは無視され、メッセージはデータ部分なしでキューに登録されます。詳細は、tpalloc()
を参照してください。
len
Flags
tperrno
にTPEBLOCK
が設定されます。このフラグが設定されていて、ターゲットのキューが別のアプリケーションによって排他的にオープンされているなどのブロッキング条件が存在する場合には、呼出しは異常終了し、tperrno
にTPEDIAGNOSTIC
が設定され、TPQCTL構造体の診断フィールドはQMESHARE
に設定されます。
TPNOBLOCK
が設定されていない場合に、ブロッキング状態が存在すると、その状態が解消されるかタイムアウト(トランザクション・タイムアウトまたはブロッキング・タイムアウト)が発生するまで、呼出し側はブロックされます。タイムアウトが発生すると、呼出しは異常終了し、tperrno
はTPETIMEに設定されます。
TPSIGRSTRT
が指定されておらず、システム・コールがシグナルによって中断された場合、tpenqplus()
は異常終了し、tperrnoにTPGOTSIG
が設定されます。
異常終了すると、tpenqplus()
は-1を返し、tperrno
を設定してエラーの状況を示します。エラーでないときは、メッセージは、tpenqplus()
の終了時に正常にエンキューされています。
[TPEINVAL]
[TPENOENT]
[TPETIME]
[TPEBLOCK]
[TPGOTSIG]
[TPEPROTO]
[TPESYSTEM]
[TPEOS]
[TPEDIAGNOSTIC]
[QMEINVAL]
[QMEBADRMID]
[QMENOTOPEN]
[QMETRAN]
TPNOTRAN
フラグを設定して呼び出したときに、メッセージをキューに登録するトランザクションを開始してエラーが発生しました。この診断は、Oracle Tuxedoリリース7.1以降のキュー・マネージャからは返されません。
[QMEBADMSGID]
[QMESYSTEM]
[QMEOS]
[QMEABORTED]
[QMEPROTO]
[QMEBADQUEUE]
[QMENOSPACE]
[QMERELEASE]
[QMBADDELIVERY]
[QMBADPRIORITY]
[QMBADPROCNUM]
[QMBADRESPQ]
[QMBADUMA]
[QMNOTSUPPORTED]
tpdeqplus()
- 選択されたキューから次の使用可能なメッセージを取得し、それをデータ引数で指定された場所に移動します。
#include <atmi.h>
#include <tmqentry.h>
#include <tmqreturn.h>
int tpdeqplus (qspace, qname, ctl, data, len, flags)
選択されたキューから次の使用可能なメッセージを取得し、それをデータ引数で指定された場所に移動します。選択フィルタが指定されていない場合、この関数は、メッセージの優先度に基づき先入れ/先出し(FIFO)の順序で、data引数で指定されたバッファに次の使用可能なメッセージを戻します。優先度の範囲は、0(低優先度)-99(高優先度)です。たとえば、優先度1のメッセージは、常に優先度0のメッセージの前に置かれます。メッセージは、メッセージの優先度に基づき、先入れ/先出しの順序で配置されます。選択フィルタが指定されている場合、選択基準に一致するメッセージのみが取得されます。メッセージがない、または選択基準に一致するメッセージがない場合、戻りステータスはQMENOMSG
になります。
アプリケーションでは、各メッセージのPSBのステータス・フィールドをチェックし、そのメッセージがリカバリ可能配信モードで送信されているかどうかを判断する必要があります。リカバリ可能メッセージを受信した場合、tpqconfirmmsg
関数を呼び出し、メッセージ・リカバリ・ジャーナルのディスク記憶域からそのメッセージを削除します。リカバリ可能メッセージの受信が確認されない場合、そのメッセージはリカバリ・システムによって保持されたままになり、アプリケーションでそのキューからデタッチし、再びアタッチしたときに再配信されます。
tpdepplus()
を使用するには、まずtpqattach()
を呼び出す必要があります。
表1-7に、tpdepplus()
がサポートする引数を示します。
qspace
qname
data
tpalloc()
によって割り当てられたバッファを指す必要があります。メッセージがtpdeqplus
に渡されるバッファよりも大きい場合、バッファはメッセージを格納できる大きさまで拡張されます。メッセージ・バッファのサイズに変化があるかどうかを判別するには、tpdeqplus()
が発行される前の(合計の)サイズを*len
と比較します。*len
のほうが大きい場合、バッファは拡張されており、そうでない場合は、バッファのサイズは変更されていません。*data
は、バッファ・サイズの増加以外の理由でも変化する可能性があることに注意してください。終了時に*len
が0である場合は、デキューされたメッセージにはデータ部がなく、*data
も*dataが指すバッファも変更されていません。*dataまたはlenがNULLの場合はエラーになります。詳細は、tpalloc()
を参照してください。 呼出し側がトランザクション・モードにあり、TPNOTRAN
フラグが設定されていない場合は、メッセージはトランザクション・モードでキューから取り出されます。この結果、tpdeqplus()
が正常終了してコール元のトランザクションが正常にコミットされると、リクエストはキューから削除されます。呼出し側のトランザクションが、明示的に、またはトランザクション・タイムアウトあるいはなんらかの通信エラーの結果としてロールバックされると、メッセージはキュー上に残されます。つまり、キューからのメッセージの削除もロールバックされます。同じトランザクション内で、同じメッセージの登録と取出しを行うことはできません。 呼出し側がトランザクション・モードにないか、またはTPNOTRAN
フラグが設定されている場合は、メッセージはトランザクション・モードではキューから取り出されません。トランザクション・モードでない場合に通信エラーまたはタイムアウトが発生した場合、アプリケーションには、メッセージが正しくキューから取り出されたかどうかがわからず、メッセージが失われることがあります。
len
ctrl
MSG_CLAS_
で始まります。クラス・シンボルの定義の詳細は、tmqsym.hインクルード・ファイルを参照してください。UNIXおよびNTシステムでは、tmqsym.hインクルード・ファイルは編集できません。アプリケーションで使用するタイプおよびクラスのシンボルを定義するインクルード・ファイルを作成する必要があります。
msg_type
引数の値にシンボリック名が使用できます。シンボリックなタイプ名はMSG_TYPE_
で始まります。タイプ・シンボルの定義の詳細は、tmqsym.h
インクルード・ファイルを参照してください。
tpqconfirmmsg
関数を使用して明示的に確認された。ACKは、受信側アプリケーションによる2番目のtpdeqplusの呼出しの後に送信される暗黙的な確認応答である場合もあります。
OTMQ_DIP_ACK
およびOTMQ_DEL_WF
を設定した場合、ACKメッセージはtpenqplus
で読み取り、クライアントはACKメッセージを読み取るために別のAPIを呼び出す必要はありません。
tpenqplus
関数がメッセージが届くまで待機する時間の最大値を指定します。メッセージが届く前にタイムアウトが発生した場合、ステータス・コードOTMQ_TIMEOUT
が戻されます。timeoutの値に0を指定すると、タイムアウトはデフォルト値の30秒に設定されます。
psb
引数は、リカバリ可能メッセージの送受信時に使用されます。PSB構造体には、次のリスト1-5に示すようなメッセージ・リカバリ・システムからのステータス情報が格納され、メッセージの送受信の後にチェックできます。
struct psb_t {
long type_of_psb; /* PSB type */
long del_psb_status; /* The completion status of the function. It contains the status from TuxMsgQ. It can also contain a value of TPSUCCESS when the message is not sent recoverably. */
long uma_psb_status; /* The completion status of the undeliverable message action (UMA). The PSB UMA status indicates if the UMA was not executed or applicable. */
long psb_reserved[6]; /* reserved filed */
};
typedef struct psb_t PSB;
注: | この構造体はすでにatmi.h で定義されています。 |
q_name
を指定します。送信側プログラムでは、レスポンス・メッセージを受信するため、replyqueue
引数に指定したキューにアタッチする必要があります。送信側プログラムで、そのqspace外のレスポンス・キューを割り当てることはできません。
data
tpalloc()
によって割り当てられたバッファを指定し、lenには、キューに登録されるバッファ内のデータの長さを指定する必要があります。長さを指定する必要のないタイプのバッファ(FMLフィールド化バッファなど)をdataが指す場合、lenは無視されます。dataがNULLの場合、lenは無視され、メッセージはデータ部分なしでキューに登録されます。詳細は、tpalloc()
を参照してください。
len
Flags
tperrno
にTPEBLOCK
が設定されます。このフラグが設定されていて、ターゲットのキューが別のアプリケーションによって排他的にオープンされているなどのブロッキング条件が存在する場合には、呼出しは異常終了し、tperrno
にTPEDIAGNOSTIC
が設定され、TPQCTL構造体の診断フィールドはQMESHARE
に設定されます。
TPNOBLOCK
が設定されていない場合に、ブロッキング状態が存在すると、その状態が解消されるかタイムアウト(トランザクション・タイムアウトまたはブロッキング・タイムアウト)が発生するまで、呼出し側はブロックされます。タイムアウトが発生すると、呼出しは異常終了し、tperrno
はTPETIME
に設定されます。
TPSIGRSTRT
が指定されておらず、システム・コールがシグナルによって中断された場合、tpenqplus()
は異常終了し、tperrno
にTPGOTSIG
が設定されます。
異常終了すると、tpdeqplus()
は-1を返し、tperrnoを設定してエラーの状況を示します。そうでない場合は、tpdeqplus()
から戻ったとき、キューは正常にデキューされています。
異常終了すると、tpdeqplus()
はtperrno
を次のいずれかの値に設定します。(特記しないかぎり、エラーが呼出し側のトランザクションに影響を及ぼすことはありません。)
[TPEINVAL]
[TPENOENT]
[TPEOTYPE]
TPNOCHANGE
がflagsに設定されていますが、*data
のタイプおよびサブタイプが、デキューされたメッセージのタイプおよびサブタイプと一致しません。いずれの場合も、*data
、その内容、および*len
はいずれも変更されません。 呼出しがトランザクション・モードで行われ、このエラーが発生すると、トランザクションは中断のみになり、メッセージはキューに残ります。
[TPETIME]
[TPEBLOCK]
[TPGOTSIG]
[TPEPROTO]
[TPESYSTEM]
[TPEOS]
[TPEDIAGNOSTIC]
[QMEINVAL]
[QMEBADRMID]
[QMENOTOPEN]
[QMEBADMSGID]
[QMESYSTEM]
[QMEOS]
[QMEABORTED]
[QMEPROTO]
[QMEBADQUEUE]
[QMENOMSG]
[QMBADPRIORITY]
[QMNOTDCL]
tpqpublish()
- トピック・データのパブリッシュに使用します。
#include <atmi.h>
#include <tmqentry.h>
#include <tmqreturn.h>
int tpqpublish (topic_name, data, len, flags)
コール元は、tpqpublish()
をトピック・データのパブリッシュに使用します。トピックは、topicおよびdataで指定され、dataはNULLでない場合にデータを指します。トピックおよびそのデータは、Oracle Tuxedo ATMIのEventBrokerによって、topicに対する評価が成功するサブスクリプションを持ち、dataに対する評価が成功するオプションのフィルタ・ルールを持つすべてのサブスクライバにディスパッチされます。
表1-9に、tpqpublish()
がサポートする引数を示します。
topicname
topicname
は、「TMQ:QNOT:QSPACE:usertopic
」などのように、「TMQ:<QNOT>:qspaceの名前
」で始まる最長32文字までのヌル終端文字列です。また、ドット(.)はOracle Tuxedo ATMIシステムによって定義されるイベントの頭文字として使用されるため、topicname
の最初の文字にはドットを使用できません。topicnameの「TMQ:QNOT:qspaceの名前
」は、すべてのユーザー・トピックの接尾辞であり、単独ではユーザー・トピックの名前として使用できません。「QNOT」は必須ではありません。しかし、topicnameに「QNOT
」が含まれているのは、パブリッシュされるメッセージがAVAIL/UNAVALI
メッセージであることを意味しています。
data
tpalloc()
によって以前に割り当てたバッファを指定し、lenには、バッファ内のイベントとともにポストするバッファに入っているデータの長さを指定する必要があります。長さを指定する必要のないタイプのバッファ(FMLフィールド化バッファなど)をdataが指す場合、lenは無視されます。dataがNULLの場合、lenは無視され、イベントはデータなしでポストされます。
Flags
TPNOTRAN
がセットされていない場合は、パブリッシャされたトピックは、トランザクション・モードのEventBrokerに渡され、これは、EventBrokerがイベントをパブリッシャのトランザクションの一部として処理できるようにするためです。ブローカは、トランザクションによるイベント通知を、tpqsubscribe()
に渡されるctl->flagsパラメータのTPEVTRAN
ビットで設定されているサービス・ルーチンおよび安定ストレージ上のキューのサブスクリプションのみにディスパッチします。EventBrokerは、クライアントへの通知、およびtpqsubscribe()
に渡されるctl->
flagsパラメータでTPEVTRAN
ビットの設定を使用しなかったサービス・ルーチンおよび安定ストレージ上のキューにあるサブスクリプションのディスパッチも行いますが、これはパブリッシャ・プロセスのトランザクションの一部としてではありません。
tpqpublish()
は確認応答のない一方向のパブリッシュになります。このような状況は、イベント用にTPEVTRAN
が設定されている場合でも起こります(この設定には、tpqsubscribe()
に渡されるctl.flagsパラメータを使用します)。パブリッシャがトランザクションの内部にある場合、関連するサービスがイベントに失敗すると、tpqpublish()
はTPESVCFAIL
を戻します。 次に、有効なフラグの一覧を示します。
tpqpublish()
に、EventBrokerがトピックに対するすべてのサブスクリプションを処理するまで待機せずに戻るように通知します。TPNOREPLY
がセットされると、tpqpublish()
が成功して戻ったかどうかにかかわらず、tpurcode()
はゼロに設定されます。呼出しプロセスがトランザクション・モードにあるとき、TPNOTRAN
が設定されないかぎりこの設定は使用できません。
tperrno
にはTPEBLOCK
が設定されます。TPNOBLOCK
が指定されていないときにブロッキング条件が存在すると、呼出し側は、その条件が解消されるか、またはタイムアウト(トランザクションまたはブロッキング)が発生するまではブロックされます。
TPSIGRSTRT
が指定されていない場合にシグナルがシステム・コールを中断させると、tpqpublish()
は異常終了し、tperrno
にはTPGOTSIG
が設定されます。
異常終了すると、tpqpublish()
は-1を返し、tperrno
を設定してエラーの状況を示します。そうでない場合は、メッセージは、tpqpublish()
の終了時に正常にブロードキャストされています。
[TPEINVAL]
[TPENOENT]
[TPETIME]
[TPEBLOCK]
[TPGOTSIG]
[TPEPROTO]
[TPESYSTEM]
[TPEOS]
tpqsubscribe()
- トピックのサブスクライブに使用します。
#include <atmi.h>
#include <tmqentry.h>
#include <tmqreturn.h>long tpqsubscirbe (topic, filter, ctl, flags)
コール元は、tpqsubscribe()
をトピックのサブスクライブに使用します。topicは、正規表現を含む、最長255文字のヌル終端文字列を指定します。filterを指定する場合は、ブール値のフィルタ・ルールを含む文字列を指定し、このルールは、TMQEVTがトピックをポストする前に正しく評価されます。パブリッシュされたトピックの受信では、TMQEVTにより、パブリッシュされたtopicの文字列に存在するフィルタ・ルールが適用されます。データがフィルタ・ルールのチェックにパスした場合は、TMQEVTは通知メソッドを呼び出し、そうでない場合は、ブローカは対応する通知メソッドを呼び出しません。呼出し側は、異なるフィルタ・ルールを利用して同じイベントを何度でもサブスクライブすることができます。
表1-10に、tpqsubscribe()
がサポートする引数を示します。
topic
TMQ:<QNOT>:qspaceの名前
」で始まる最長32文字までのヌル終端文字列です(たとえば、「TMQ:QNOT:QSPACE:usertopic
」)。また、ドット(.)はOracle Tuxedo ATMIシステムによって定義されるイベントの頭文字として使用されるため、topicの最初の文字にはドットを使用できません。topicの「TMQ:QNOT:qspaceの名前
」は、すべてのユーザー・トピックの接尾辞であり、単独ではユーザー・トピックの名前として使用できません。「QNOT
」は必須ではありません。しかし、topicに「QNOT
」が含まれている場合、パブリッシュされるメッセージがAVAIL/UNAVALI
メッセージであることを示しています。
filter
/* Subscription Control structure */
struct tpevctl_t {
long flags;
char name1[XATMI_SERVICE_NAME_LENGTH];
char name2[XATMI_SERVICE_NAME_LENGTH];
TPQCTL qctl;
};
typedef struct tpevctl_t TPEVCTL;
次に示すのは、トピックのサブスクリプションの制御オプションであるctl->flags要素の有効なビットの一覧です。
ctl->name1
およびctl->name2で名前を指定されたキュー・スペースにエンキューすることを示します。それは、パブリッシュされたトピック名がtopicに対して正常に評価され、TMQEVTにより、パブリッシュされたデータがトピックに関連するフィルタ・ルールに対してテストされたときです。データがフィルタ・ルールを通過した場合、またはトピックに対応したフィルタ・ルールが存在しない場合は、TMQEVTは、ctl->name1
で名前を指定されたキュー・スペースおよびctl->name2
で名前を指定されたキューに、トピックとともにパブリッシュされたデータとあわせて、メッセージをエンキューします。キュー・スペースとキューの名前は、Oracle Tuxedo ATMIシステムの有効な任意のキュー・スペースおよびキューの名前で、サブスクリプションの実行時に存在している場合と存在していない場合があります。
ctl->qctl
には、パブリッシュされたトピックをエンキューするようにTMQEVTに指示するオプションも追加できます。オプションを何も指定しない場合は、ctl->qctl
.flagsにはTPNOFLAGS
を設定してください。そうでない場合は、tpenqplus
のサブセクション「制御パラメータ」で説明されているオプションが設定できます。TPEVQUEUE
は相互に排他的なフラグです。ctl->flags
にもTPEVTRAN
が設定されていて、tpqpublish()
を呼び出しているプロセスがトランザクション・モードである場合、TMQEVTは、そのパブリッシャのトランザクションの一部となるようにパブリッシュされたトピックおよびそのデータをエンキューします。TMQEVTは、トランザクションをサポートするサーバー・グループに属している必要があります(詳細は「 UBBCONFIG
」を参照)。ctl->flags
にTPEVTRAN
が設定されない場合は、TMQEVTは、そのパブリッシャのトランザクションの一部とならないようにパブリッシュされたトピックおよびそのデータをエンキューします。
ctl->flags
にTPEVQUEUE
を設定し、ctl->qctl.flags
にTPQCOORID
が設定されなかった場合、topic、filter、ctl->name1
に設定されたキュー・スペース名、およびctl->name2
に設定されたキュー名が、TMQEVTにすでに知られている(相関識別子が指定された)サブスクリプションが持つそれらの値と一致するとtpqsubscribe()
は異常終了します。さらに、ctl->qctl.flags
にTPQCOORID
が設定されている場合は、topic
、filter
、ctl->name1
、ctl->name2
およびctl->qctl.corrid
がTMQEVTにすでに知られている(同じ相関識別子が指定された)サブスクリプションのデータと一致すると、tpqsubscribe()
は異常終了します。
TPEVTRAN
と同時に指定し、イベントの通知時にリソースが利用できない場合は、EventBroker
は、そのトランザクションを強制終了するようにポスト元に戻します。つまり、サブスクリプションが保持されている場合でも、リソースが使用できなければポスト元のトランザクションは異常終了します。
flags
tperrno
にはTPEBLOCK
が設定されます。TPNOBLOCK
が指定されていないときにブロッキング条件が存在すると、呼出し側は、その条件が解消されるか、またはタイムアウト(トランザクションまたはブロッキング)が発生するまではブロックされます。
TPSIGRSTRT
が指定されていない場合にシグナルがシステム・コールを中断させると、tpqsubscribe()
は異常終了し、tperrno
にはTPGOTSIG
が設定されます。
異常終了すると、tpqsubscribe()
は-1を返し、tperrno
を設定してエラーの状況を示します。そうでない場合は、トピックは、tpqsubscribe()
の終了時に正常にサブスクライブされており、サブスクリプション・ハンドルが戻されます。
[TPEINVAL]
[TPENOENT]
[TPETIME]
[TPEBLOCK]
[TPGOTSIG]
[TPEPROTO]
[TPESYSTEM]
[TPEOS]
[TPELIMIT]
tpqunsubscribe()
- サブスクリプションの削除に使用します。
#include <atmi.h>
#include <tmqentry.h>
#include <tmqreturn.h>
int tpqunsubscirbe (subscription,flags)
表1-11に、tpqunsubscribe()
がサポートする引数を示します。
Subscription
tpqsubscribe()
から戻されるサブスクリプション・ハンドルです。subscriptionをワイルドカード値の-1に設定すると、tpqunsubscribe()
が、呼出し側のプロセスが以前に行ったすべての非永続型のサブスクリプションを削除する指示になります。非永続型のサブスクリプションとは、tpqsubscribe()
のctl->flags
パラメータにTPEVPERSIST
ビットを設定して行われたサブスクリプションのことです。永続サブスクリプションは、tpqsubscribe()
から返されたハンドルを使用することによってのみ削除できます。
flags
tperrno
にはTPEBLOCK
が設定されます。TPNOBLOCK
が指定されていないときにブロッキング条件が存在すると、呼出し側は、その条件が解消されるか、またはタイムアウト(トランザクションまたはブロッキング)が発生するまではブロックされます。
TPSIGRSTRT
が指定されていない場合にシグナルがシステム・コールを中断させると、tpunsubscribe()
は異常終了し、tperrno
にはTPGOTSIG
が設定されます。
異常終了すると、tpqunsubscribe()
はtperrno
を次のいずれかの値に設定します。(特記しないかぎり、エラーが呼出し側のトランザクションに影響を及ぼすことはありません。)
[TPEINVAL]
[TPENOENT]
[TPETIME]
[TPEBLOCK]
[TPGOTSIG]
[TPEPROTO]
[TPESYSTEM]
[TPEOS]
tpqconfirmmsg()
- 明示的な確認を必要とするメッセージの受信を確認します。
#include <atmi.h>
#include <tmqentry.h>
#include <tmqreturn.h>int tpqconfirmmsg (seq_number, force_j)
明示的な確認を必要とするメッセージの受信を確認します。これは、明示的な確認用に構成されているキューに送信されたリカバリ可能メッセージか、または明示的な受信確認が必要なACK配信モードを使用して送信されたメッセージの場合です。アプリケーションでは、受信した各メッセージのPSBのステータス・フィールドを調べ、そのメッセージが明示的な確認を必要としているかどうかを判断する必要があります。
リカバリ可能メッセージを受信した場合、アプリケーションでは、メッセージ・リカバリ・ジャーナルのディスク記憶域からそのメッセージを削除するため、tpqconfirmmsg
関数を呼び出す必要があります。リカバリ可能メッセージの受信が確認されない場合、そのメッセージはリカバリ・システムによって保持されたままになり、アプリケーションでそのキューからデタッチし、再びアタッチしたときに再配信されます。
OTMQでは、リカバリ・ジャーナル内の次に続くメッセージが配信されるときに、リカバリ可能メッセージの受信を自動的に確認できます。この機能は、暗黙的な確認と呼ばれます。
すべてのキューは、暗黙的な確認または明示的な確認のどちらかで構成されます。メッセージ・キューの構成方法の詳細は、『Oracle Tuxedo Message Queueコマンド・リファレンス・ガイド』の tmqadmin
に関する項を参照してください。
正常に配信されたリカバリ可能メッセージは、事後確認ジャーナル(PCJ)に記録できます。tpqconfirmmsg
関数では、システムが現在、メッセージを格納するように構成されていない場合、force_j
引数を使用してPCJファイルにメッセージを書き込みます。正常に配信されたリカバリ可能メッセージは、tpqconfirmmsg
関数を使用して明示的に確認しないかぎり、PCJファイルには書き込むことができないことに注意してください。
tpqconfirmmsg()
を使用するには、まずtpqattach()
を呼び出す必要があります。
注: | tpqconfirmmsg() は非同期呼出しであり、その戻り時には、まだリカバリ・ジャーナル・ディスク記憶域内のリカバリ可能メッセージがリカバリ・システムによって削除されていないことがあります。 |
表1-12に、tpqconfirmmsg()
がサポートする引数を示します。
tpdeqplus
関数のPSBで受信側プログラムに渡されます。
force_j
異常終了すると、tpqconfirmmsg()
はtperrno
を次のいずれかの値に設定します。(特記しないかぎり、エラーが呼出し側のトランザクションに影響を及ぼすことはありません。)
[TPEINVAL]
[TPENOENT]
[TPETIME]
[TPESYSTEM]
[TPEOS]
tpqsetselect()
- アプリケーションの開発者が、メッセージを受け取るための複雑な選択基準を定義できます。
#include <atmi.h>
#include <tmqentry.h>
#include <tmqreturn.h>int tpqsetselect (selection_array, num_masks, index_handle)
アプリケーションの開発者が、メッセージを受け取るための複雑な選択基準を定義できます。選択配列により、キューに対して、メッセージ受信の優先度、範囲チェックのための2つの比較キー、およびメッセージがキューから選択される順序を決定する順序キーによる検索を指定します。
tpqsetselect
関数は、メッセージ読取り用のOTMQ関数のsel_filter
引数として使用されるインデックス・ハンドルを作成します。選択インデックス・ハンドルがtpdeqplus
に渡されると、各受信メッセージが比較キーのkey_1
およびkey_2と比較されます。メッセージが両方のキーと一致する場合(論理的なAND操作)、そのメッセージは一致メッセージのセットに追加されます。選択されたメッセージが配信される順序は、順序キーによって決定されます。
tpqsetselect()
を使用するには、まずtpqattach()
を呼び出す必要があります。
表1-13に、tpqsetselect()
がサポートする引数を示します。
selection_array
tmqentry.h
に次のように定義されています: typedef struct _selection_array_component_tp {
char qspace[TMQSNAMELEN+1];
char queue[QNAMELEN+1];
TM32I priority;
TM32I key_1_offset;
TM32I key_1_size;
TM32I key_1_value;
TM32I key_1_oper;
TM32I key_2_offset;
TM32I key_2_size;
TM32I key_2_value;
TM32I key_2_oper;
TM32I order_offset;
TM32I order_size;
TM32I order_order;
char key_value_qspace[TMQSNAMELEN+1]; union {
otmq_correlation_id correlation_id;
otmq_sequence_number sequence number
} extended_key
} selection_array_component_tp;
selection_array_component_tp
データ構造体には次のようなコンポーネントがあります。
表1-15に、Select_Queue
構造体のこの部分の引数に適用できる有効な値を示します。
selection_array_component_tp
構造体のこの部分に適用できる引数および有効な値を示します。
Order Keyの部分には、次の表に示す変数を格納します。
相関識別子 相関識別子は、メッセージに関連付けられた32バイトのユーザー定義の識別子です。key_1_offsetまたはkey_2_offsetフィールドのいずれかの値としてOTMQ_CORRELATION_ID
指定された場合、指定された相関識別子の値がメッセージとの一致のチェックに使用されます。相関識別子は各メッセージに1つであるため、OTMQ_CORRELATION_ID
は比較キーの1つのみに指定でき、両方のキーに相関識別子を指定するとTPEINVALのエラーになります。 OTMQ_CORRELATION_IDがorder_offsetフィールドの値として指定されると、その相関識別子を持つメッセージは、order_orderフィールドで指定された順序で戻されます。 順序番号 メッセージの順序番号は各メッセージごとに一意の値です。順序番号はPSBに格納されています。アプリケーションでは、メッセージの順序番号をPSBから取得する必要があり、それに対するどのような変更も許されません。 注意: アプリケーションでは、相関識別子または順序番号による選択のため、2つのキーのうちの1つのみを指定できます。
num_masks
index_handle
tpdeqplus
、tpqgetmsga
およびtpqcancelselect
関数で、TPQCTLのsel_filter
引数として渡されます。OTMQの実装では、32767までのインデックス・ハンドルが提供されます。
異常終了すると、tpqsetselect()
はtperrno
を次のいずれかの値に設定します。
[TPEINVAL]
[TPENOENT]
[TPETIME]
[TPESYSTEM]
[TPEOS]
tpqcancelselect()
- 以前に生成された選択マスクに関連付けられている選択配列およびインデックス・ハンドルを解放します。
#include <atmi.h>
#include <tmqentry.h>
#include <tmqreturn.h>
int tpqcancelselect (index_handle)
以前に生成された選択マスクに関連付けられている選択配列およびインデックス・ハンドルを解放します。index_handle
および関連付けられた選択マスクはtpqsetselect
関数を使用して作成されます。選択マスクが非同期読取りリクエストで使用されるとき、この関数はまた、参照されたindex_handle
を使用している保留中のtpqgetmsga
リクエストを取り消します。
tpqcancelselect()
を使用するには、まずtpqattach()
を呼び出す必要があります。
表1-18に、tpqcancelselect()
がサポートする引数を示します。
index_handle
異常終了すると、tpqcancelselect()
はtperrno
を次のいずれかの値に設定します。
[TPEINVAL]
[TPENOENT]
[TPETIME]
[TPESYSTEM]
[TPEOS]
tpqreadjrn()
- OTMQのローカル・グループ・ジャーナルからメッセージを読み取ります。
#include <atmi.h>
#include <tmqentry.h>
#include <tmqreturn.h>
int tpqreadjrn (qspace, qname, ctl, type, odata, olen, timeout)
OTMQのジャーナルからメッセージを読み取ります。tpqreadjrn()
を使用するには、まずtpqattach()
を呼び出す必要があります。
表1-19に、tpqreadjrn
がサポートする引数を示します。
qspace
qname
type
odata
olen
timeout
tpqreadjrn
関数がメッセージが届くまで待機する時間の最大値を指定します。メッセージが届く前にタイムアウトが発生した場合、ステータス・コードOTMQ_TIMEOUTが戻されます。timeoutの値に0を指定すると、タイムアウトはデフォルト値の30秒に設定されます。
異常終了すると、tpqreadjrn()
はtperrno
を次のいずれかの値に設定します。そうでない場合は、tpqreadjrn()
から戻ったとき、メッセージは正常に読み取られています。tpqerrno()
およびtpqstrerror()
を使用し、詳細なOTMQのエラー番号や詳細な文字列のエラー・メッセージを取得できます。
[TPEINVAL]
[TPENOENT]
[TPEOTYPE]
[TPETIME]
[TPEBLOCK]
[TPGOTSIG]
[TPEPROTO]
[TPESYSTEM]
[TPEOS]
[TPEDIAGNOSTIC]
次の診断値は、キューからのメッセージの取出し中に返されます。
tpqshowpending()
- 選択されたキューのリストの保留中メッセージの数をリクエストします。
#include <atmi.h>
#include <tmqentry.h>
#include <tmqreturn.h>
int tpqshowpending ( qspace, count, in_q_list, out_pend_list)
need to follow the style of others API
選択されたキューのリストの保留中メッセージの数をリクエストします。tpqshowpending
関数を使用するには、保留中のメッセージ数を取得するメッセージ・キューの番号、および保留中のメッセージ数を取得したいキュー名のリストを指定します。この関数の戻り値は、各キューのメッセージの合計数です。
tpqshowpending()
を使用するには、まずtpqattach()
を呼び出す必要があります。
注: | out_pend_list 配列を割り当てる必要があります。リストされるキューの数は「count」によって決まるため、キューのリストの配列が適切に割り当てられるように注意してください。 |
表1-20に、tpqshowpending
がサポートする引数を示します。
qspace
count
in_q_list
out_pend_list
異常終了すると、tpqshowpending()
はtperrnoを次のいずれかの値に設定します。tpqerrno()
およびtpqstrerror()
を使用し、詳細なOTMQのエラー番号や詳細な文字列のエラー・メッセージを取得できます。
[TPEINVAL]
[TPENOENT]
[TPETIME]
[TPESYSTEM]
[TPEOS]
tpqgetmsga()
- メッセージ受信の非同期通知をリクエストします。
#include <atmi.h>
#include <tmqentry.h>
#include <tmqreturn.h>
int tpqgetmsga (qspace, qname, ctl, data, len , uact, uact_param , uflag, flags)
メッセージ受信の非同期通知をリクエストします。OTMQでは、tpqgetmsga
関数はTuxedoの非請求型メッセージを使用して実装されています。tpqgetmsga
を呼び出すと、それ自身のUNSOLメッセージ・ハンドラを登録します。tpqgetmsga
の選択条件に一致するキューにメッセージが届くと、そのデキューされるメッセージは、UNSOLメッセージを介してアプリケーションに送信されます。また、UNSOLメッセージが届き、アプリケーションにそれ自身のメッセージ処理コールバック関数(またはフラグ)が設定されている場合、ユーザーのコールバック関数が呼び出され(またはフラグが「1」に設定され)、メッセージがtpqgetmsga
によってデキューされたことがアプリケーションに通知されます。
UNSOLメッセージがtpqgetmsga
のインフラストラクチャであるため、このAPIの呼出しに際し、UBB内のNOTIFYを「IGNORE」に設定してはいけません。また、一部の制限として、OpenVMSでは通知モードの「SIGNAL」はサポートされていません。
キューにリカバリ可能メッセージが送信されたとき、受信側プログラムでは、tpqconfirmmsg
関数を使用してメッセージの受信を確認できます。tpqconfirmmsg
関数により、正常に配信されたメッセージをメッセージ・リカバリ・システムから削除できます。
tpqgetmsga()
を使用するには、まずtpqattach()
を呼び出す必要があります。
表1-21に、tpqgetmsga
がサポートする引数を示します。
qspace
qname
ctl
data
len
uact
uact_param
uflag
tpqgetmsga
関数が完了したときに設定されるフラグ番号のint値を指定します。tpqgetmsga
関数が実行されるとき、このフラグはクリアされます。この引数の値が指定されない場合、フラグは使用されません。
flags
異常終了すると、tpqgetmsga()
は-1を返し、tperrno
を設定してエラーの状況を示します。tpqerrno()
およびtpqstrerror()
を使用し、詳細なOTMQのエラー番号や詳細な文字列のエラー・メッセージを取得できます。
tpqgetmsga()
はtperrno
を次のいずれかの値に設定します。(特記しないかぎり、エラーがコール元のトランザクションに影響を及ぼすことはありません。)
[TPEINVAL]
[TPENOENT]
[TPETIME]
[TPESYSTEM]
[TPEOS]
[TPEDIAGNOSTIC]
tpqcancelget()
- sel_filter引数で指定された値に一致するすべての保留中tpqgetmsgaリクエストを取り消します。
#include <atmi.h>
#include <tmqentry.h>
#include <tmqreturn.h>
int tpqcancelget (qspace, sel_filter , flags)
sel_filter引数で指定された値に一致するすべての保留中tpqgetmsga
リクエストを取り消します。保留中のtpqgetmsgaリクエストが取り消されるとき、OTMQのステータス・ブロック(PSB)の配信ステータスがOTMQ__CANCEL
に設定され、指定したアクションのルーチンがキューイングされます。tpqcancelget関数は、tpqcancelget関数とtpqgetmsga関数のリクエストの間の適切な同期が取られるように、完了まで待機します。
未処理のtpqgetmsga
関数のリクエストはすべて、tpqexit関数またはイメージの終了により取り消されます。
tpqcancelget()
を使用するには、まずtpqattach()
を呼び出す必要があります。
注: | tpqcancelgetでは、sel_filterパラメータに(0 | 0)を設定したpriority >= 0でsel_filter == NULLのtpqgetmsgaを取り消すことができます。 |
注: | 「sel_filter」が(OTMQ_PQ_PRI | x)と設定されているtpqcancelgetでは、「priority」がxで「sel_filter」がNULLに設定されているtpqgetmsgaは取り消すことができません。 |
表1-22に、tpqcancelget
がサポートする引数を示します。
qspace
sel_filter
tpdeqplus
関数の項を参照してください。複合的な選択フィルタの作成方法については、 tpqsetselect
関数の項を参照してください。
Flags
異常終了すると、tpqcancelget()は-1を返し、tperrnoを設定してエラーの状況を示します。tpqerrno()およびtpqstrerror()を使用して、詳細なOTMQのエラー番号および詳細な文字列のエラー・メッセージを取得できます。
tpqcancelget()はtperrnoを次のいずれかの値に設定します。
[TPEINVAL]
[TPENOENT]
[TPETIME]
[TPESYSTEM]
[TPEOS]
tpqerrno()
- OTMQシステム・コールのerrnoを取得します。
#include <atmi.h>
#include <tmqentry.h>
#include <tmqreturn.h>Int tpqerrno(void);
tpqerrno()
は、OTMQシステム・コールのエラー・コードを取得するために使用します。
正常終了すると、tpqstrerror()
はエラー・メッセージ・テキストを含む文字列を指すポインタを返します。
errが無効なエラー・コードの場合、tpqstrerror()
は、NULLを返します。
tpqexit()
- アプリケーションとOTMQキュー・サービス間のすべてのアタッチメントを終了します。
#include <atmi.h>
#include <tmqentry.h>
#include <tmqreturn.h>
int tpqexit(void);
アプリケーションとOTMQキュー・サービス間のすべてのアタッチメントを終了します。無制限キューおよび複数リソース・キュー以外のキューでは、キュー内のすべての保留中メッセージが破棄されます。永続的にアクティブなキュー内のメッセージを残しておくには、tpexitq
を呼び出す前にTUXMSGQ_NOFLUSH_Q
オプションを指定してtpdetachqを呼び出します。
異常終了すると、tpqcancelget()は-1を返し、tperrnoを設定してエラーの状況を示します。
[TPEPROTO]
[TPESYSTEM]
[TPESVCERR]
tpqstrerror()
- Oracle Tuxedo Message Queueのエラー・メッセージ文字列の詳細を取得します。
#include <atmi.h>
#include <tmqentry.h>
#include <tmqreturn.h>Void tpqstrerror(int tpqerrno);
tpqstrerror()
はTMQ_CATからエラー・メッセージのテキストを取得するために使用します。errは、OTMQシステムの関数呼出しが-1またはその他の異常終了値を返した場合にtperrno
に設定されるエラー・コードです。
tpqstrerror()
によって戻されたポインタをuserlog()
またはUNIX関数fprintf()
に対する引数として使用できます。
表1-23に、tpqstrerror()
がサポートする引数を示します。
正常終了すると、tpqstrerror()
はエラー・メッセージ・テキストを含む文字列を指すポインタを返します。
errが無効なエラー・コードの場合、tpqstrerror()
は、char *を返します。