メッセージのキューへの登録

次は、tpenqueue() の構文です。

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

tpenqueue() が呼び出されると、qspace で識別されるキュー・スペース内の qname キューにメッセージを格納するようにシステムが指示されます。メッセージは data が指すバッファ内にあり、その長さは len で示されます。flags にビット設定を行うと、システムに tpenqueue() 呼び出しの処理方法が通知されます。登録されたメッセージおよび応答の処理方法のさらに詳しい情報は、ctl が指す TMQCTL 構造体で定義されます。

tpenqueue(3c) の引数

tpenqueue(): qspace 引数

qspace は、管理者によって既に作成されたキュー・スペースを識別します。サーバがコンフィギュレーション・ファイルの SERVERS セクションで定義されている場合、そのサーバが提供するサービス名は、実際のキュー・スペース名 (GROUPS セクションの OPENINFO パラメータの一部として指定されます) のエイリアスになります。たとえば、アプリケーションがサーバ TMQUEUE を使用する場合、qspace 引数が指す値は、TMQUEUE が宣言するサービス名になります。サービス名のエイリアスが何も定義されていない場合、デフォルトのサービス名はサーバ名 TMQUEUE と同じになります。その場合、コンフィギュレーション・ファイルには次の内容が記述されています。

TMQUEUE　
        SRVGRP = QUE1  SRVID = 1　
        GRACE = 0  RESTART = Y CONV = N　
        CLOPT="-A"

または

        CLOPT = "-s TMQUEUE"　

サーバ・グループ QUE1 のエントリには、OPENINFO パラメータを使用して、リソース・マネージャ、デバイスのパス名、およびキュー・スペース名を指定します。クライアント・プログラムにおける qspace 引数は、次のように記述されます。

if (tpenqueue("TMQUEUE", "STRING", (TPQCTL *)&qctl,
        (char *)reqstr, 0,0) == -1) {
        Error checking
}

tpenqueue(): qname 引数

キュー・スペース内で、キューを使用してサービスを呼び出している場合、メッセージ・キューは要求を処理できるアプリケーション・サービスに従って命名されます。qname は、そのようなアプリケーション・サービスを指すポインタです。それ以外の場合、qname は、アプリケーション (メッセージをキューに登録したアプリケーション、または別のアプリケーション) によってキューから取り出されるまで、メッセージを格納しておく場所を単に示す名前です。

tpenqueue(): data および len 引数

tpenqueue(): flags 引数

flags の値は、tpdequeue() 呼び出しの処理方法を BEA Tuxedo システムに通知するために使用されます。次は、有効なフラグです。

TPQCTL 構造体

tpenqueue() の 3 番目の引数は、TPQCTL 型の構造体へのポインタです。TPQCTL 構造体には、アプリケーションで使用されるメンバと BEA Tuxedo システムで使用されるメンバがあり、アプリケーション・プログラムとキュー機能間の両方向でパラメータがやり取りされます。tpenqueue() を呼び出すクライアントは、フラグを設定して、システム側で入力する必要のあるフィールドをマークします。この構造体は、tpdequeue() でも使用されます。一部のフィールドは、アプリケーションが tpdequeue() を呼び出すまで使用されません。次のコード例は、この構造体全体を示しています。

tpqctl_t 構造体

#define TMQNAMELEN 15
#define TMMSGIDLEN 32 
#define TMCORRIDLEN 32

struct tpqctl_t {            /* キュー・プリミティブの制御パラメータ */
     long flags;             /* どの値が設定されるかのかを示します。 */
     long deq_time;          /* キューから取り出すときの絶対時間/相対時間 */
     long priority;          /* 登録優先順位 */
     long diagnostic;        /*  失敗の原因を示します。 */
     char msgid[TMMSGIDLEN];  /* 既存メッセージの ID (そのメッセージの前に登録されます) */
     char corrid[TMCORRIDLEN];    /* メッセージを識別するときに使用される相関識別子 */
     char replyqueue[TMQNAMELEN+1];   /* 応答メッセージ用のキューの名前 */
     char failurequeue[TMQNAMELEN+1]; /* 異常終了メッセージを登録するキューの名前 */
     CLIENTID cltid;         /* 発信元クライアントのクライアント識別子 */
     long urcode;            /* アプリケーション・ユーザ戻りコード */
     long appkey;            /* アプリケーション認証クライアント・キー */
     long delivery_qos;      /* サービスの配信品質 */
     long reply_qos;         /* サービスの応答メッセージの品質 */
     long exp_time;          /* 有効期限の時間 */
}; 
typedef struct tpqctl_t TPQCTL;

以下は、tpenqueue() の入力情報を制御する flags パラメータの有効なフラグです。

tpenqueue() からの出力では、次のフィールドが TPQCTL 構造体に設定されます。

long flags;        /* どの値が設定されるかを示します。 */
char msgid[32];    /* キューに登録されたメッセージの ID */
long diagnostic;   /* 失敗の原因を示します。 */

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

キューの順序の無効化

キューの作成時に、管理者が tpenqueue() 呼び出しでキュー上のメッセージの順序を無効にできるようにした場合、次の 2 つの方法でこの機能を利用できます。この 2 つの方法は、相互に排他的です。flags に TPQTOP を設定すると、メッセージをキューの先頭に置くことができます。または、flags に TPQBEFOREMSGID、ctl->msgid に既存のメッセージの ID を設定して、メッセージを特定の既存のメッセージの前に置くこともできます。この方法では、メッセージ ID を使用できるように、以前の呼び出しで取得されたメッセージ ID が保存されていることが必要です。管理者は、キューでサポートされている方法を通知する必要があります。キューは、この 2 つのいずれかまたは両方を使用できるように、あるいはどちらも使用できないように作成できます。

キューの優先順位の無効化

ctl->priority に値を設定して、メッセージの優先順位を指定することができます。この値は、1 以上 100 以下の範囲でなければなりません。数値が高いほど優先順位も高くなります。キューの順序付けパラメータの中に priority が含まれていない場合、ここで優先順位を設定しても取り出しの順序には影響しません。ただし、優先順位の値は保持されるので、メッセージがキューから取り出されるときに検査されます。

メッセージの使用可能時間の設定

deq_time に、絶対時間またはキューへの登録が完了してからの相対時間として、メッセージが処理されるまで時間を指定できます。flags に、TPQTIME_ABS または TPQTIME_REL のいずれかを設定して、値の処理方法を指定できます。キューは、time を順序付けの基準として作成することができます。その場合、メッセージは使用可能時間によって順序付けされます。

キューからメッセージを取り出す相対時間、たとえば、キューへの登録操作が完了してから nnn 秒などを指定する場合、deq_time に秒数を指定し、flags に TPQTIME_REL を設定します。

tpenqueue() とトランザクション

tpenqueue() の呼び出し元がトランザクション・モードにある場合に、TPNOTRAN が設定されていないと、キューへの登録は呼び出し元のトランザクション内で行われます。呼び出し元は、TPENQUEUE() が成功したか失敗したかによって、メッセージがキューに登録されたかどうかを判断できます。呼び出しが正常に行われると、メッセージがキューに登録されたことが保証されます。呼び出しが失敗すると、メッセージがキューに登録された部分も含めて、トランザクションがロールバックされます。

tpenqueue() の呼び出し元がトランザクション・モードにない場合、または TPNOTRAN が設定されている場合、メッセージは呼び出し元のトランザクションとは別のトランザクションでキューに登録されます。tpenqueue() への呼び出しが正常な戻り値を返した場合、メッセージがキューに登録されたことが保証されます。tpenqueue() の呼び出しが通信エラーまたはタイムアウトによって失敗した場合は、その障害がメッセージ登録の前に発生したのか後に発生したのか、呼び出し元には判断できません。

呼び出し元がトランザクション・モードにないときに TPNOTRAN を指定しても意味がありません。