リファレンス・ガイド

Oracle Tuxedo Message Queue関数リファレンス

tpdequeue()

名前

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フラグが設定されている場合は、メッセージはトランザクション・モードではキューから取り出されません。トランザクション・モードでない場合に通信エラーまたはタイムアウトが発生した場合、アプリケーションには、メッセージが正しくキューから取り出されたかどうかがわからず、メッセージが失われることがあります。

次に、有効なflagsの一覧を示します。

TPNOTRAN

TPNOBLOCK

TPNOTIME

TPNOCHANGE

TPSIGRSTRT

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

このフラグを設定すると、ctlmsgidによって指定されたメッセージ識別子を持つメッセージのエキューをリクエストします。メッセージ識別子は、事前のtpenqueue()呼出しによって戻されます。メッセージが別のキューに移動すると、メッセージ識別子が変わることに注意してください。また、メッセージ識別子の値は32バイトすべてが意味を持つため、ctlmsgidによって指定された値を完全に初期化する必要があります(たとえば、NULL文字で埋めるなど)。

TPQGETBYCORRID

このフラグを設定すると、ctlcorridによって指定された相関識別子を持つメッセージのデキューをリクエストします。相関識別子は、アプリケーションがtpenqueue()でメッセージをエンキューしたときに指定されます。また、相関識別子の値は32バイト全体が意味を持つため、ctlcorridによって指定された値を完全に初期化する必要があります(たとえば、NULL文字で埋めるなど)。

TPQWAIT

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()の呼出しが正常終了し、メッセージが明示的な優先度でキューに登録された場合、この優先度がctlpriorityに格納されます。優先度は1以上100以内の範囲内で、数値が高いほど優先度も高くなります。つまり、高い数値のメッセージが低い数値のメッセージよりも先にキューから取り出されます。優先度によって順序付けられていないキューの場合、値は情報にすぎません。

TPQMSGID

このフラグが設定されていてtpdequeue()の呼出しが正常終了した場合、メッセージ識別子がctlmsgidに格納されます。メッセージ識別子の値は、32バイト全体が意味を持ちます。

TPQCORRID

このフラグが設定されていてtpdequeue()の呼出しが正常終了し、メッセージが相関識別子によってエンキューされた場合、この相関識別子がctlcorridに格納されます。相関識別子の値は、32バイト全体が意味を持ちます。Oracle Tuxedo ATMI /Qが提供するメッセージの応答には、すべて元のリクエスト・メッセージの相関識別子が付いています。

TPQDELIVERYQOS

TPQREPLYQOS

TPQREPLYQ

このフラグが設定されていてtpdequeue()の呼出しが正常終了し、メッセージが応答キューによってエンキューされた場合、応答キューの名前がctlreplyqueueに格納されます。メッセージへの応答は、リクエスト・メッセージと同じキュー・スペース内の指定されたキューに登録されます。

TPQFAILUREQ

このフラグが設定されていてtpdequeue()の呼出しが正常終了し、メッセージが失敗キューによってエンキューされた場合、失敗キューの名前がctlfailurequeueに格納されます。異常終了メッセージは、リクエスト・メッセージと同じキュー・スペース内の指定された異常終了キューに登録されます。

flagsパラメータの残りのビットは、tpdequeue()が呼び出されるとクリア(0に設定)されます。これには、TPQTOP、TPQBEFOREMSGID、TPQTIME_ABS、TPQTIME_REL、TPQEXPTIME_ABS、TPQEXPTIME_REL、およびTPQEXPTIME_NONEが含まれます。これらのビットは、tpenqueue()の入力情報を制御するflagsパラメータの有効なビットです。

tpdequeue()の呼出しが失敗してtperrnoにTPEDIAGNOSTICが設定された場合は、失敗の原因を示す値がctldiagnosticに戻されます。戻される可能性のある値は、この後の「診断」の項で定義しています。

また出力時には、tpdequeue()の呼出しが正常に終了すると、ctlappkeyにアプリケーション認証キーが設定され、ctlcltidにリクエストの発信元であるクライアントの識別子が設定され、ctlurcodeにメッセージ登録時に設定されたユーザー戻り値が設定されます。

ctlパラメータがNULLである場合、入力フラグはTPNOFLAGSとみなされ、アプリケーション・プログラムは出力情報を利用できません。

戻り値

異常終了すると、tpdequeue()は -1を返し、tperrnoを設定してエラー条件を示します。

エラー

異常終了時には、tpdequeue()はtperrnoを次のいずれかの値に設定します。(特記しないかぎり、エラーが呼出し側のトランザクションに影響を及ぼすことはありません。)

[TPEINVAL]

[TPENOENT]

[TPEOTYPE]

[TPETIME]

[TPEBLOCK]

[TPGOTSIG]

[TPEPROTO]

[TPESYSTEM]

[TPEOS]

[TPEDIAGNOSTIC]

診断

次の診断値は、キューからのメッセージの取出し中に返されます。

[QMEINVAL]

[QMEBADRMID]

[QMENOTOPEN]

[QMETRAN]

[QMEBADMSGID]

[QMESYSTEM]

[QMEOS]

[QMEABORTED]

[QMEPROTO]

[QMEBADQUEUE]

[QMENOMSG]

[QMEINUSE]

[QMESHARE]

関連項目

qmadmin(1), tpalloc(3c)、tpenqueue()、 APPQ_MIB(5)、 TMQUEUE(5)

tpenqueue()

名前

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データ構造体を介してアプリケーションによって制御されます。デフォルトのキューの順序は、キューの作成時に設定されます。

次に、有効なflagsの一覧を示します。

TPNOTRAN

TPNOBLOCK

TPNOTIME

TPSIGRSTRT

キューへのメッセージ登録に関する追加情報は、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

TPQBEFOREMSGID

このフラグを設定すると、キューの順序はオーバーライドされ、メッセージはctlmsgidによって識別されるメッセージの前に登録されます。このリクエストは、順序付けを無効にするようにキューが設定されているかどうかによって、使用できない場合があります。TPQTOPとTPQBEFOREMSGIDは、相互に排他的なフラグです。また、メッセージ識別子の値は32バイト全体が意味を持つため、ctlmsgidによって指定された値を完全に初期化する必要があります(たとえば、NULL文字で埋めるなど)。

TPQTIME_ABS

このフラグが設定されると、メッセージはctldeq_timeによって指定された時間の後で使用可能になります。deq_timeは、time(2)、mktime(3)、またはgp_mktime(3c)によって生成された絶対時間値、つまり協定世界時(UTC)の1970年1月1日00:00:00から経過した秒数です。TPQTIME_ABSとTPQTIME_RELは、相互に排他的なフラグです。絶対時間は、キュー・マネージャ・プロセスが常駐するマシンの時計によって決定されます。

TPQTIME_REL

このフラグを設定すると、メッセージは、キューへの登録操作が完了してからの相対時間経過後に使用可能になります。ctldeq_timeは、キューの登録が完了した後、出されたリクエストが処理されるまでの遅延秒数を指定します。TPQTIME_ABSとTPQTIME_RELは、相互に排他的なフラグです。

TPQPRIORITY

このフラグを設定すると、メッセージがエンキューされる際の優先度がctlpriorityに格納されます。優先度は、1以上100以下の範囲でなければなりません。数値が高いほど優先度も高くなり、高い数値のメッセージが低い数値のメッセージより先にキューから取り出されます。優先度によって順序付けられていないキューでは、この値は参考として使用されます。

TPQCORRID

このフラグが設定されている場合、ctlcorridで指定された相関識別子の値は、メッセージがtpdequeue()によってデキューされるときに使用できます。この識別子は、キューに登録されるすべての応答メッセージまたは異常終了メッセージに付加されるので、アプリケーションは応答を特定のリクエストに結び付けることができます。また、相関識別子の値は32バイト全体が意味を持つため、ctlcorridで指定された値を完全に初期化する必要があります(たとえば、NULL文字で埋めるなど)。

TPQREPLYQ

このフラグが設定されると、ctlreplyqueueで指定された応答キューは、待機メッセージに関連付けられます。メッセージに対する応答はすべて、リクエスト・メッセージと同じキュー・スペース内の指定されたキューに登録されます。この文字列は、NULLで終了しなければなりません(最大15文字)。

TPQFAILUREQ

このフラグが設定されると、ctlfailurequeueで指定された失敗キューは、待機メッセージに関連付けられます。(1)キューに登録されたメッセージがTMQFORWARD()によって処理され、(2) TMQFORWARDが-dオプションで開始され、さらに(3)サービスが失敗してNULL以外の応答を戻す場合は、その応答と関連するtpurcodeによって構成される失敗メッセージが、元のリクエスト・メッセージと同じキュー・スペース内で指定されたキューに登録されます。この文字列はNULLで終了し、15文字以下であることが必要です。

TPQDELIVERYQOS、TPQREPLYQOS

TPQEXPTIME_ABS

TPQEXPTIME_REL

TPQEXPTIME_NONE

また、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()の呼出しが正常終了した場合、メッセージ識別子がctlmsgidに格納されます。メッセージ識別子の値は32バイト全体が意味を持つため、ctlmsgidに格納される値は完全に初期化されます(たとえば、NULL文字で埋めるなど)。初期化に使用される実際の埋め文字は、Oracle Tuxedo ATMI /Qコンポーネントのリリースによって異なります。

制御構造体の残りのメンバーは、tpenqueue()への入力に使用されません。

tpenqueue()の呼出しが失敗してtperrnoにTPEDIAGNOSTICが設定された場合は、失敗の原因を示す値がctldiagnosticに戻されます。戻される可能性のある値は、この後の「診断」の項で定義しています。

このパラメータがNULLである場合、入力フラグは、TPNOFLAGSとみなされ、アプリケーション・プログラムは出力情報を利用できません。

戻り値

異常終了すると、tpenqueue()は -1を返し、tperrnoを設定してエラー条件を示します。エラーでないときは、メッセージは、tpenqueue()の終了時に正しくキューに登録されます。

エラー

異常終了時には、tpenqueue()はtperrnoを次のいずれかの値に設定します。(特記しないかぎり、エラーが呼出し側のトランザクションに影響を及ぼすことはありません。)

[TPEINVAL]

[TPENOENT]

[TPETIME]

[TPEBLOCK]

[TPGOTSIG]

[TPEPROTO]

[TPESYSTEM]

[TPEOS]

[TPEDIAGNOSTIC]

診断

次の診断値は、キューへのメッセージの登録中に返されます。

[QMEINVAL]

[QMEBADRMID]

[QMENOTOPEN]

[QMETRAN]

[QMEBADMSGID]

[QMESYSTEM]

[QMEOS]

[QMEABORTED]

[QMEPROTO]

[QMEBADQUEUE]

[QMENOSPACE]

[QMERELEASE]

[QMESHARE]

関連項目

qmadmin(1)、gp_mktime(3c)、tpacall(3c)、tpalloc(3c)、tpdequeue()、tpinit(3c)、tpsprio(3c)、APPQ_MIB(5)、TMQFORWARD(5)、TMQUEUE(5)

tpqattach()

名前

tpqattach() - アプリケーション・プログラムをメッセージ・キューにアタッチすることにより、OTMQのメッセージ・キュー・スペースに接続します。

形式

#include <atmi.h>
#include <tmqentry.h>
#include <tmqreturn.h>
int tpqattach (qspace, queue, ctl, qattachctl, flags)

説明

メッセージ・キュー・スペースは、システム、共有グローバル・メモリー・セクションおよびファイルに存在するメッセージ・キューのコレクションで、同じサーバー・プロセスによって処理されます。OTMQのメッセージ・キューは、メッセージが格納および取得されるメモリーまたはディスクの領域です。OTMQ環境の構成方法については、ご使用のプラットフォーム用のインストレーションおよび構成ガイドを参照してください。

OTMQメッセージを受信するには、少なくとも1つのメッセージ・キューにアタッチする必要があります。アプリケーションは、tpqattach関数により、次の手順でアタッチできます。

アプリケーションでは、プライマリまたはセカンダリのアタッチメントを指定できます。すべてのアプリケーションにはプライマリ・キューがあります。それに加え、1つ以上のセカンダリ・キューにアタッチできます。プライマリ・キューは、キューの作成コマンドでセカンダリ・キューの所有者として構成できます。セカンダリ・キューの所有者であるプライマリ・キューにアタッチすると、プライマリ・キューにアタッチされるのと同時に、そのアプリケーションは自動的にセカンダリ・キューにもアタッチされます。

それに加え、複数リソースのキューにアタッチできます。複数リソースのキューは、多くのアプリケーションからの読取りが可能で、グループ定義の一部として構成されます。

表1-2に、tpqattach()がサポートする引数を示します。

qspace

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);

Flags

戻り値

[TPEINVAL]

[TPENOENT]

[TPETIME]

[TPEBLOCK]

[TPESYSTEM]

[TPEOS]

[TPEDIAGNOSTIC]

[QMEINVAL]

[QMESYSTEM]

[QMEOS]

[QMEABORTED]

[QMEBADQUEUE]

tpqdetach()

名前

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()がサポートする引数を示します。

qspace

queue

detach_opt_list

detach_opt_len

msgs_flushed

flags

戻り値

異常終了すると、tpqdetach()は-1を返し、tperrnoを設定してエラーの状況を示します。そうでない場合は、tpqdetach()から戻ったとき、キューは正常にデタッチされています。

Errors:

[TPEINVAL]

[TPENOENT]

[TPETIME]

[TPEBLOCK]

[TPGOTSIG]

[TPEPROTO]

[TPESYSTEM]

[TPEOS]

tpqbind()

名前

tpqbind() - 実行時に、キュー名をキューの参照に動的に関連付けます。

形式

#include <atmi.h>
#include <tmqentry.h>
#include <tmqreturn.h>
int tpqbind (qspace , pNameCtl , scope, timeout);

説明

実行時に、キュー名をキューの参照に動的に関連付けます。これにより、サーバー・アプリケーションで実行時に動的にキューのエイリアスをサービスに登録できます。これによりエンド・ユーザーは、通常のホスト・コンピュータが停止しても、サービスが別のホスト・コンピュータで提供されていることを意識せずにサービスにアクセスできます。tpqbind()を使用するには、まずtpqattach()を呼び出す必要があります。

表1-4に、tpqbind()がサポートする引数を示します。

qspace

pNameCtl

scope

timeout

戻り値

異常終了すると、tpqbind()は-1を返し、tperrnoを設定してエラーの状況を示します。そうでない場合は、tpqbind()から戻ったとき、キューのエイリアスは正常にバインドされています。

Errors:

[TPEINVAL]

[TPENOENT]

[TPETIME]

[TPEPROTO]

[TPESYSTEM]

[TPEOS]

tpqlocate()

名前

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()がサポートする引数を示します。

qspace

pNameCtl

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;

wait_mode

req_id

resp_q

scope

timeout

戻り値

異常終了すると、tpqlocate()は-1を返し、tperrnoを設定してエラーの状況を示します。そうでない場合は、tpqlocate()から戻ったとき、キューは正常に検出されています。

Errors:

[TPEINVAL]

[TPENOENT]

[TPETIME]

[TPEPROTO]

[TPESYSTEM]

[TPEOS]

tpenqplus()

名前

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

制御パラメータ

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.

len

Flags

戻り値

異常終了すると、tpenqplus()は-1を返し、tperrnoを設定してエラーの状況を示します。エラーでないときは、メッセージは、tpenqplus()の終了時に正常にエンキューされています。

Errors:

[TPEINVAL]

[TPENOENT]

[TPETIME]

[TPEBLOCK]

[TPGOTSIG]

[TPEPROTO]

[TPESYSTEM]

[TPEOS]

[TPEDIAGNOSTIC]

[QMEINVAL]

[QMEBADRMID]

[QMENOTOPEN]

[QMETRAN]

[QMEBADMSGID]

[QMESYSTEM]

[QMEOS]

[QMEABORTED]

[QMEPROTO]

[QMEBADQUEUE]

[QMENOSPACE]

[QMERELEASE]

[QMBADDELIVERY]

[QMBADPRIORITY]

[QMBADPROCNUM]

[QMBADRESPQ]

[QMBADUMA]

[QMNOTSUPPORTED]

tpdeqplus()

名前

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

len

ctrl

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;

data

len

Flags

戻り値

異常終了すると、tpdeqplus()は-1を返し、tperrnoを設定してエラーの状況を示します。そうでない場合は、tpdeqplus()から戻ったとき、キューは正常にデキューされています。

Errors:

異常終了すると、tpdeqplus()はtperrnoを次のいずれかの値に設定します。(特記しないかぎり、エラーが呼出し側のトランザクションに影響を及ぼすことはありません。)

[TPEINVAL]

[TPENOENT]

[TPEOTYPE]

[TPETIME]

[TPEBLOCK]

[TPGOTSIG]

[TPEPROTO]

[TPESYSTEM]

[TPEOS]

[TPEDIAGNOSTIC]

[QMEINVAL]

[QMEBADRMID]

[QMENOTOPEN]

[QMEBADMSGID]

[QMESYSTEM]

[QMEOS]

[QMEABORTED]

[QMEPROTO]

[QMEBADQUEUE]

[QMENOMSG]

[QMBADPRIORITY]

[QMNOTDCL]

tpqpublish()

名前

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

data

Flags

戻り値

異常終了すると、tpqpublish()は-1を返し、tperrnoを設定してエラーの状況を示します。そうでない場合は、メッセージは、tpqpublish()の終了時に正常にブロードキャストされています。

Errors:

[TPEINVAL]

[TPENOENT]

[TPETIME]

[TPEBLOCK]

[TPGOTSIG]

[TPEPROTO]

[TPESYSTEM]

[TPEOS]

tpqsubscribe()

名前

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

filter

ctrl

flags

戻り値

異常終了すると、tpqsubscribe()は-1を返し、tperrnoを設定してエラーの状況を示します。そうでない場合は、トピックは、tpqsubscribe()の終了時に正常にサブスクライブされており、サブスクリプション・ハンドルが戻されます。

Errors:

[TPEINVAL]

[TPENOENT]

[TPETIME]

[TPEBLOCK]

[TPGOTSIG]

[TPEPROTO]

[TPESYSTEM]

[TPEOS]

[TPELIMIT]

tpqunsubscribe()

名前

tpqunsubscribe() - サブスクリプションの削除に使用します。

形式

#include <atmi.h>
#include <tmqentry.h>
#include <tmqreturn.h>
int tpqunsubscirbe (subscription,flags)

説明

サブスクリプションの削除に使用します。

表1-11に、tpqunsubscribe()がサポートする引数を示します。

Subscription

flags

戻り値

異常終了すると、tpqunsubscribe()はtperrnoを次のいずれかの値に設定します。(特記しないかぎり、エラーが呼出し側のトランザクションに影響を及ぼすことはありません。)

[TPEINVAL]

[TPENOENT]

[TPETIME]

[TPEBLOCK]

[TPGOTSIG]

[TPEPROTO]

[TPESYSTEM]

[TPEOS]

tpqconfirmmsg()

名前

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()を呼び出す必要があります。

表1-12に、tpqconfirmmsg()がサポートする引数を示します。

seq_number

force_j

戻り値

異常終了すると、tpqconfirmmsg()はtperrnoを次のいずれかの値に設定します。(特記しないかぎり、エラーが呼出し側のトランザクションに影響を及ぼすことはありません。)

[TPEINVAL]

[TPENOENT]

[TPETIME]

[TPESYSTEM]

[TPEOS]

tpqsetselect()

名前

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

表1-15に、Select_Queue構造体のこの部分の引数に適用できる有効な値を示します。

num_masks

index_handle

戻り値

異常終了すると、tpqsetselect()はtperrnoを次のいずれかの値に設定します。

[TPEINVAL]

[TPENOENT]

[TPETIME]

[TPESYSTEM]

[TPEOS]

tpqcancelselect()

名前

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()

名前

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()はtperrnoを次のいずれかの値に設定します。そうでない場合は、tpqreadjrn()から戻ったとき、メッセージは正常に読み取られています。tpqerrno()およびtpqstrerror()を使用し、詳細なOTMQのエラー番号や詳細な文字列のエラー・メッセージを取得できます。

[TPEINVAL]

[TPENOENT]

[TPEOTYPE]

[TPETIME]

[TPEBLOCK]

[TPGOTSIG]

[TPEPROTO]

[TPESYSTEM]

[TPEOS]

[TPEDIAGNOSTIC]

診断

次の診断値は、キューからのメッセージの取出し中に返されます。

tpqshowpending()

名前

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()を呼び出す必要があります。

表1-20に、tpqshowpendingがサポートする引数を示します。

qspace

count

in_q_list

out_pend_list

戻り値

異常終了すると、tpqshowpending()はtperrnoを次のいずれかの値に設定します。tpqerrno()およびtpqstrerror()を使用し、詳細なOTMQのエラー番号や詳細な文字列のエラー・メッセージを取得できます。

[TPEINVAL]

[TPENOENT]

[TPETIME]

[TPESYSTEM]

[TPEOS]

tpqgetmsga()

名前

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

flags

戻り値

異常終了すると、tpqgetmsga()は-1を返し、tperrnoを設定してエラーの状況を示します。tpqerrno()およびtpqstrerror()を使用し、詳細なOTMQのエラー番号や詳細な文字列のエラー・メッセージを取得できます。

tpqgetmsga()はtperrnoを次のいずれかの値に設定します。(特記しないかぎり、エラーがコール元のトランザクションに影響を及ぼすことはありません。)

[TPEINVAL]

[TPENOENT]

[TPETIME]

[TPESYSTEM]

[TPEOS]

[TPEDIAGNOSTIC]

tpqcancelget()

名前

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()を呼び出す必要があります。

表1-22に、tpqcancelgetがサポートする引数を示します。

qspace

sel_filter

Flags

戻り値

異常終了すると、tpqcancelget()は-1を返し、tperrnoを設定してエラーの状況を示します。tpqerrno()およびtpqstrerror()を使用して、詳細なOTMQのエラー番号および詳細な文字列のエラー・メッセージを取得できます。

tpqcancelget()はtperrnoを次のいずれかの値に設定します。

[TPEINVAL]

[TPENOENT]

[TPETIME]

[TPESYSTEM]

[TPEOS]

tpqerrno()

名前

tpqerrno() - OTMQシステム・コールのerrnoを取得します。

形式

#include <atmi.h>
#include <tmqentry.h>
#include <tmqreturn.h>
Int tpqerrno(void);

説明

tpqerrno()は、OTMQシステム・コールのエラー・コードを取得するために使用します。

戻り値

正常終了すると、tpqstrerror()はエラー・メッセージ・テキストを含む文字列を指すポインタを返します。

errが無効なエラー・コードの場合、tpqstrerror()は、NULLを返します。

tpqexit()

名前

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()

名前

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()がサポートする引数を示します。

tpqerrno()

戻り値

正常終了すると、tpqstrerror()はエラー・メッセージ・テキストを含む文字列を指すポインタを返します。

errが無効なエラー・コードの場合、tpqstrerror()は、char *を返します。