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

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

01 TPQUEDEF-REC.
   COPY TPQUEDEF.
01 TPTYPE-REC.
   COPY TPTYPE.
01 DATA-REC.
   COPY User Data.
01 TPSTATUS-REC.
   COPY TPSTATUS.
CALL "TPENQUEUE" USING TPQUEDEF-REC TPTYPE-REC DATA-REC TPSTATUS-REC.

TPENQUEUE() が呼び出されると、TPQUEDEF-REC 内の QSPACE-NAME で識別されるキュー・スペース内の TPQUEDEF-REC の QNAME キューにメッセージを格納するようにシステムに指示します。メッセージは DATA-REC にあり、TPTYPE-REC 内の LEN にはメッセージの長さが入ります。TPQUEDEF-REC の設定によって、システムに TPENQUEUE() 呼び出しの処理方法が通知されます。キューに登録されるメッセージ、および応答の処理方法についてのさらに詳しい情報は、TPQUEDEF-REC 構造体で定義されます。

TPENQUEUE() の引数

TPENQUEUE():TPQUEDEF-REC 引数内の QSPACE-NAME

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

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

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

 01 TPQUEDEF-REC.
    COPY TPQUEDEF.
 01 TPTYPE-REC.
    COPY TPTYPE.
 01 TPSTATUS-REC.
    COPY TPSTATUS.
 01 USER-DATA-REC  PIC X(100).
*
*
*
 MOVE LOW-VALUES TO TPQUEDEF-REC.
 MOVE "TMQUEUE" TO QSPACE-NAME IN TPQUEDEF-REC.
 MOVE "STRING" TO QNAME IN TPQUEDEF-REC.
 SET TPTRAN IN TPQUEDEF-REC TO TRUE.
 SET TPBLOCK IN TPQUEDEF-REC TO TRUE.
 SET TPTIME IN TPQUEDEF-REC TO TRUE.
 SET TPSIGRSTRT IN TPQUEDEF-REC TO TRUE.
 MOVE LOW-VALUES TO TPTYPE-REC.
 MOVE "STRING" TO REC-TYPE IN TPTYPE-REC.
 MOVE LENGTH OF USER-DATA-REC TO LEN IN TPTYPE-REC.
 CALL "TPENQUEUE" USING
         TPQUEDEF-REC
         TPTYPE-REC
         USER-DATA-REC
         TPSTATUS-REC.

TPENQUEUE():TPQUEDEF-REC 引数内の QNAME

TPENQUEUE():DATA-REC および TPTYPE-REC 引数内の LEN

DATA-REC には、処理対象のメッセージが入ります。TPTYPE-REC 内の LEN は、メッセージの長さを指定します。BEA Tuxedo のレコード・タイプには、LEN を指定する必要がないもの (VIEW など) もあります。その場合、引数は無視されます。TPTYPE-REC 内の RECTYPE が SPACES の場合、DATA-REC および LEN は無視され、メッセージはデータ部なしでキューに登録されます。

TPENQUEUE():TPQUEDEF-REC の設定値

TPQUEDEF-REC の設定値は、TPENQUEUE() 呼び出しの処理方法を BEA Tuxedoシステムに通知するために使用されます。次は、有効な設定です。

TPQUEDEF-REC 構造体

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

TPQUEDEF-REC 構造体

        05 TPBLOCK-FLAG         PIC S9(9) COMP-5.　
                88 TPBLOCK              VALUE 0.　
                88 TPNOBLOCK            VALUE 1.　
        05 TPTRAN-FLAG  PIC S9(9) COMP-5.　
                88 TPTRAN               VALUE 0.　
                88 TPNOTRAN             VALUE 1.　
        05 TPTIME-FLAG  PIC S9(9) COMP-5.　
                88 TPTIME               VALUE 0.　
                88 TPNOTIME             VALUE 1.　
        05 TPSIGRSTRT-FLAG      PIC S9(9) COMP-5.　
                88 TPNOSIGRSTRT         VALUE 0.　
                88 TPSIGRSTRT           VALUE 1.　
        05 TPNOCHANGE-FLAG      PIC S9(9) COMP-5.　
                88 TPCHANGE             VALUE 0.　
                88 TPNOCHANGE           VALUE 1.　
        05 TPQUE-ORDER-FLAG     PIC S9(9) COMP-5.　
                88 TPQDEFAULT           VALUE 0.　
                88 TPQTOP               VALUE 1.　
                88 TPQBEFOREMSGID       VALUE 2.　
        05 TPQUE-TIME-FLAG      PIC S9(9) COMP-5.　
                88 TPQNOTIME            VALUE 0.　
                88 TPQTIME-ABS          VALUE 1.　
                88 TPQTIME-REL          VALUE 2.　
        05 TPQUE-PRIORITY-FLAG  PIC S9(9) COMP-5.　
                88 TPQNOPRIORITY        VALUE 0.　
                88 TPQPRIORITY          VALUE 1.　
        05 TPQUE-CORRID-FLAG    PIC S9(9) COMP-5.　
                88 TPQNOCORRID          VALUE 0.　
                88 TPQCORRID            VALUE 1.　
        05 TPQUE-REPLYQ-FLAG    PIC S9(9) COMP-5.　
                88 TPQNOREPLYQ          VALUE 0.　
                88 TPQREPLYQ            VALUE 1.　
        05 TPQUE-FAILQ-FLAG     PIC S9(9) COMP-5.　
                88 TPQNOFAILUREQ        VALUE 0.　
                88 TPQFAILUREQ          VALUE 1.　
        05 TPQUE-MSGID-FLAG     PIC S9(9) COMP-5.　
                88 TPQNOMSGID           VALUE 0.　
                88 TPQMSGID             VALUE 1.　
        05 TPQUE-GETBY-FLAG     PIC S9(9) COMP-5.　
                88 TPQGETNEXT           VALUE 0.　
                88 TPQGETBYMSGIDOLD     VALUE 1.　
                88 TPQGETBYCORRIDOLD    VALUE 2.　
                88 TPQGETBYMSGID        VALUE 3.　
                88 TPQGETBYCORRID       VALUE 4.　
        05 TPQUE-WAIT-FLAG      PIC S9(9) COMP-5.　
                88 TPQNOWAIT            VALUE 0.　
                88 TPQWAIT              VALUE 1.　
        05 TPQUE-DELIVERY-FLAG  PIC S9(9) COMP-5.　
                88 TPQNODELIVERYQOS     VALUE 0.　
                88 TPQDELIVERYQOS       VALUE 1.　
        05 TPQUEQOS-DELIVERY-FLAG       PIC S9(9) COMP-5.　
                88 TPQQOSDELIVERYDEFAULTPERSIST VALUE 0.　
                88 TPQQOSDELIVERYPERSISTENT     VALUE 1.　
                88 TPQQOSDELIVERYNONPERSISTENT  VALUE 2.　
        05 TPQUE-REPLY-FLAG     PIC S9(9) COMP-5.　
                88 TPQNOREPLYQOS                VALUE 0.　
                88 TPQREPLYQOS                  VALUE 1.　
        05 TPQUEQOS-REPLY-FLAG  PIC S9(9) COMP-5.　
                88 TPQQOSREPLYDEFAULTPERSIST    VALUE 0.　
                88 TPQQOSREPLYPERSISTENT        VALUE 1.　
                88 TPQQOSREPLYNONPERSISTENT     VALUE 2.　
        05 TPQUE-EXPTIME-FLAG   PIC S9(9) COMP-5.　
                88 TPQNOEXPTIME         VALUE 0.　
                88 TPQEXPTIME-ABS       VALUE 1.　
                88 TPQEXPTIME-REL       VALUE 2.　
                88 TPQEXPTIME-NONE      VALUE 3.　
        05 TPQUE-PEEK-FLAG      PIC S9(9) COMP-5.　
                88 TPQNOPEEK            VALUE 0.　
                88 TPQPEEK              VALUE 1.　
        05 DIAGNOSTIC           PIC S9(9) COMP-5.　
                88 QMEINVAL             VALUE -1.　
                88 QMEBADRMID           VALUE -2.　
                88 QMENOTOPEN           VALUE -3.　
                88 QMETRAN              VALUE -4.　
                88 QMEBADMSGID          VALUE -5.　
                88 QMESYSTEM            VALUE -6.　
                88 QMEOS                VALUE -7.　
                88 QMEABORTED           VALUE -8.　
                88 QMEPROTO             VALUE -9.　
                88 QMEBADQUEUE          VALUE -10.　
                88 QMENOMSG             VALUE -11.　
                88 QMEINUSE             VALUE -12.　
                88 QMENOSPACE           VALUE -13.　
                88 QMERELEASE           VALUE -14.　
                88 QMEINVHANDLE         VALUE -15.　
                88 QMESHARE             VALUE -16.　
        05 DEQ-TIME             PIC 9(9) COMP-5.　
        05 EXP-TIME             PIC 9(9) COMP-5.　
        05 PRIORITY             PIC S9(9) COMP-5.　
        05 MSGID                PIC X(32).　
        05 CORRID               PIC X(32).　
        05 QNAME                PIC X(15).　
        05 QSPACE-NAME          PIC X(15).　
        05 REPLYQUEUE           PIC X(15).　
        05 FAILUREQUEUE         PIC X(15).　
        05 CLIENTID OCCURS 4 TIMES PIC S9(9) COMP-5.　
        05 APPL-RETURN-CODE     PIC S9(9) COMP-5.　
        05 APPKEY               PIC S9(9) COMP-5.　

次は、TPENQUEUE の入力情報を制御するパラメータの有効な設定です。

このほかに、TPQUEDEF-REC のメンバ APPL-RETURN-CODE にユーザ戻りコードを設定することができます。この値は、メッセージをキューから取り出すために TPDEQUEUE() を呼び出すアプリケーションに返されます。

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

05 DIAGNOSTIC           PIC S9(9) COMP-5.
05 MSGID                PIC X(32).

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

TPENQUEUE() の呼び出しが失敗し、TP-STATUS に TPEDIAGNOSTIC が設定された場合、失敗の原因を示す値が DIAGNOSTIC に返されます。次は、返される値です。

キューの順序の無効化

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

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

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

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

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

次のコード例は、相対時間を使用して、メッセージをキューに登録する方法を示しています。このメッセージは、60 秒後に処理対象になります。

  01  TPQUEDEF-REC.　
      COPY TPQUEDEF.　
  01  TPTYPE-REC.　
      COPY TPTYPE.　
  01  TPSTATUS-REC.　
      COPY TPSTATUS.　
  01  USER-DATA-REC  PIC X(100).　
*　
*　
*　
  MOVE LOW-VALUES TO TPQUEDEF-REC.　
  MOVE "QSPACE1" TO QSPACE-NAME IN TPQUEDEF-REC.　
  MOVE "Q1" TO QNAME IN TPQUEDEF-REC.　
  SET TPTRAN IN TPQUEDEF-REC TO TRUE.　
  SET TPBLOCK IN TPQUEDEF-REC TO TRUE.　
  SET TPTIME IN TPQUEDEF-REC TO TRUE.　
  SET TPSIGRSTRT IN TPQUEDEF-REC TO TRUE.　
  SET TPQDEFAULT IN TPQUEDEF-REC TO TRUE.　
  SET TPQTIME-REL IN TPQUEDEF-REC TO TRUE.　
  MOVE 60 TO DEQ-TIME IN TPQUEDEF-REC.　
  SET TPQNOPRIORITY IN TPQUEDEF-REC TO TRUE.　
  SET TPQNOCORRID IN TPQUEDEF-REC TO TRUE.　
  SET TPQNOREPLYQ IN TPQUEDEF-REC TO TRUE.　
  SET TPQNOFAILUREQ IN TPQUEDEF-REC TO TRUE.　
  SET TPQMSGID IN TPQUEDEF-REC TO TRUE.　
  MOVE LOW-VALUES TO TPTYPE-REC.　
  MOVE "STRING" TO REC-TYPE IN TPTYPE-REC.　
  MOVE LENGTH OF USER-DATA-REC TO LEN IN TPTYPE-REC.　
  CALL "TPENQUEUE" USING　
          TPQUEDEF-REC　
          TPTYPE-REC　
          USER-DATA-REC　
          TPSTATUS-REC.

TPENQUEUE() およびトランザクション

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

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

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