tpenqueue(3c)

名前

tpenqueue()-メッセージをキューに登録するルーチン

形式

#include <atmi.h>
int tpenqueue(char *qspace, char *qname, TPQCTL *ctl, char *data,
long len, long flags)

機能説明

tpenqueue() は、キュー・スペース qspace 内の qname で指定されるキューに、メッセージを格納します。キュー・スペースは、キューを集めたもので、そのうちの１つのキューが qname でなければなりません。

data が NULL 以外である場合、これは事前に tpalloc() によって割り当てられたバッファを指さなければならず、len は、キューに登録されるバッファ内のデータの大きさを指定しなければなりません。長さを指定する必要のないタイプのバッファ (FML フィールド化バッファなど) を data が指す場合、len は無視されます。data が NULL の場合、len は無視され、データ部分なしでメッセージはキューに登録されます

メッセージは、qspace について定義された優先順位が事前の tpsprio() の呼び出しによって無効化されていないかぎり、この優先順位でキューに登録されます。

呼び出し元がトランザクションにあり、TPNOTRAN フラグが設定されていない場合は、メッセージは、トランザクション・モードでキューに登録されます。この結果、tpenqueue() が正常終了して呼び出し元のトランザクションが正常にコミットされると、メッセージは、トランザクションの完了後に処理されることが保証されます。呼び出し元のトランザクションが、明示的に、あるいはトランザクション・タイムアウトまたは何らかの通信エラーの結果としてロールバックされると、メッセージは、キューから削除されます (つまり、キューへのメッセージの登録もロールバックされます)。同じトランザクション内で同じメッセージの登録と取り出しを行うことはできません。

呼び出し元がトランザクション・モードにないか、または TPNOTRAN フラグが設定されている場合は、メッセージはトランザクション・モードではキューに登録されません。tpenqueue() が正常終了すれば、出されたメッセージが処理されることが保証されます。トランザクション・モードでないときに通信エラーまたはタイムアウトが発生した場合、アプリケーションにはメッセージがキューに正しく格納されたかどうかがわかりません。

メッセージが処理される順序は、この後説明するように、ctl データ構造体を介してアプリケーションによって制御されます。デフォルトのキューの順序は、キューの作成時に設定されます。

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

キューへのメッセージ登録に関する追加情報は、ctl データ構造体を介して指定できます。この情報には、デフォルトのキューの順序を無効化してキューの先頭または登録されているメッセージの前にメッセージを登録するための値、キューからメッセージを取り出すまでの絶対時間または相対時間、メッセージが期限切れになり、キューから削除される絶対時間または相対時間、メッセージ配信サービスの品質、メッセージが応答する際のサービス品質、メッセージとそのメッセージに関連付けられた応答または異常終了メッセージを結び付けるときに役立つ相関識別子、応答を登録するキューの名前、およびすべての異常終了メッセージを登録するキューの名前が含まれます。

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

制御パラメータ

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

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

long flags;            /* どの値が設定されるかの指定 */

long deq_time;         /* キューから取り出すときの絶対時間/相対時間 */  
long priority;         /* 登録優先順位 */  
long exp_time          /* 有効期限 */  
long delivery_qos      /* 配信サービスの品質 */  
long reply_qos         /* 応答サービスの品質 */  
long urcode;           /* ユーザ戻り値 */  
char msgid[32];        /* 既存メッセージの ID (要求をそのメッセージの前に
                        	* 登録するため) */
char corrid[32];       /* msg を識別するときに使用される相関識別子 */

char replyqueue[16];   /* 応答メッセージ用キューの名前 */  
char failurequeue[16]; /* 異常終了メッセージ用キューの名前 */

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

また、TPQCTL の要素 urcode にユーザ戻り値を設定することができます。この値は、メッセージをキューから取り出すアプリケーションに返されます。

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

long flags;                    /* どの値が設定されるかの指定 */

char msgid[32];                /* id of enqueued message */  
long diagnostic;               /* 異常終了の原因 */

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

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

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

戻り値

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

エラー

異常終了時には、tpenqueue() は tperrno() を次のいずれかの値に設定します(特に指定がない限り、障害は、呼び出し元のトランザクションに影響しません)。

診断

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

関連項目