名前

tpdequeue()−キューからメッセージを取り出すルーチン

形式

#include <atmi.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 の一覧を示します。

tpdequeue() が正常終了すると、アプリケーションは、ctl データ構造体を使用してメッセージに関する追加情報を取得できます。この情報には、キューから取り出されたメッセージのメッセージ識別子、すべての応答または異常終了メッセージに付随して、発信元がメッセージと元の要求を結び付けることができるようにする相関識別子、メッセージが送られるサービスの品質、メッセージの応答が送られるサービスの品質、応答が要求された場合は応答キューの名前、およびメッセージをキューから取り出すときの失敗に関する情報をアプリケーションが登録できる異常終了キューの名前が含まれます。これらについては、次に説明します。

マルチスレッドのアプリケーションの場合、TPINVALIDCONTEXT 状態のスレッドは tpdequeue() の呼び出しを発行できません。

制御パラメータ

TPQCTL 構造体は、アプリケーション・プログラムが、キューからのメッセージの取り出しに関連するパラメータを渡したり、取得したりするために使用します。TPQCTL の要素 flags は、この構造体の他のどの要素が有効であるかを示すために使用されます。

tpdequeue() への入力時には、次の要素を TPQCTL 構造体に設定できます。

long flags;            /* どの値が
                        * 設定されるかの指定 */
char msgid[32];        /* キューから取り出すメッセージの ID */
char corrid[32];       /* キューから取り出す
                        * メッセージの相関識別子 */

tpdequeue() の入力情報を制御する flags パラメータの有効なビットの一覧を次に示します。

tpdequeue() からの出力時には、次の要素が TPQCTL 構造体に設定されます。

long flags;            /* どの値が 
                        * 設定されるかの指定 */
 
long priority;         /* 登録優先順位 */ 
char msgid[32];        /* キューから取り出されたメッセージの ID */ 
char corrid[32];       /* メッセージを識別するときに
                        * 使用された相関識別子 */
long delivery_qos;     /* 配信サービスの品質 */
long reply_qos;        /* 応答メッセージのサービス品質 */
char replyqueue[16];   /* 応答のためのキュー名 */ 
char failurequeue[16]; /* 異常終了キューの名前 */ 
long diagnostic;       /* 異常終了の原因 */ 
long appkey;           /* アプリケーション認証用のクライアント 
                        * キー */ 
long urcode;           /* ユーザ戻り値 */ 
CLIENTID cltid;        /* 発信元クライアントの 
                        * クライアント識別子 */

tpdequeue() からの出力情報を制御する flags パラメータの有効なビットの一覧を次に示します。これらのビットのいずれかについて、tpdequeue() の呼び出し時にフラグ・ビットをオンにしていると、その構造体の対応する要素には、メッセージがキューに登録されたときに指定された値が格納され、そのビットは設定されたままになります。値が使用できない (つまり、メッセージがキューに登録されたときに値が指定されなかった) 場合、または tpdequeue() を呼び出したときにビットが設定されていない場合は、tpdequeue() はフラグをオフにして終了します。

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

tpdequeue() の呼び出しが異常終了して tperrno に TPEDIAGNOSTIC が設定された場合は、異常終了の原因を示す値が ctl—>diagnostic に返されます。返される可能性のある値は、この後の「診断」の項で定義しています。

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

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

戻り値

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

エラー

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

診断

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

関連項目