MQMD構造体 − メッセージ記述子
MQMD構造体は,次のフィールドから構成されます。
フィールド(データタイプ) |
内容 |
初期値 |
---|---|---|
StrucId(MQCHAR4型) |
構造体識別子 |
MQMD_STRUC_ID |
Version(MQLONG型) |
構造体バージョン番号 |
MQMD_VERSION_1 |
Report(MQLONG型) |
報告メッセージオプション |
MQRO_NONE |
MsgType(MQLONG型) |
メッセージタイプ |
MQMT_DATAGRAM |
Expiry(MQLONG型) |
メッセージ保持時間 |
MQEI_UNLIMITED |
Feedback(MQLONG型) |
報告メッセージ返答コード |
MQFB_NONE |
Encoding(MQLONG型) |
メッセージデータのマシンコード形式 |
MQENC_NATIVE |
CodedCharSetId(MQLONG型) |
メッセージデータの文字セット識別子 |
MQCCSI_Q_MGR |
Format(MQCHAR8型) |
メッセージデータのフォーマット名 |
MQFMT_NONE |
Priority(MQLONG型) |
メッセージ優先度 |
MQPRI_PRIORITY_AS_Q_DEF |
Persistence(MQLONG型) |
メッセージ永続性 |
MQPER_PERSISTENCE_AS_Q_DEF |
MsgId(MQBYTE24型) |
メッセージ識別子 |
MQMI_NONE |
CorrelId(MQBYTE24型) |
相関識別子 |
MQCI_NONE |
BackoutCount(MQLONG型) |
ロールバック回数 |
0 |
ReplyToQ(MQCHAR48型) |
応答キュー名 |
ヌル文字列/空白 |
ReplyToQMgr(MQCHAR48型) |
応答キューマネジャ名 |
ヌル文字列/空白 |
UserIdentifier(MQCHAR12型) |
ユーザ識別子 |
ヌル文字列/空白 |
AccountingToken(MQBYTE32型) |
課金トークン |
MQACT_NONE |
ApplIdentityData(MQCHAR32型) |
アプリケーション識別データ |
ヌル文字列/空白 |
PutApplType(MQLONG型) |
登録アプリケーションタイプ |
MQAT_NO_CONTEXT |
PutApplName(MQCHAR28型) |
登録アプリケーション名 |
ヌル文字列/空白 |
PutDate(MQCHAR8型) |
登録日付 |
ヌル文字列/空白 |
PutTime(MQCHAR8型) |
登録時刻 |
ヌル文字列/空白 |
ApplOriginData(MQCHAR4型) |
登録元データ |
ヌル文字列/空白 |
GroupId(MQBYTE24型)※ |
グループ識別子 |
MQGI_NONE |
MsgSeqNumber(MQLONG型)※ |
メッセージシーケンス番号 |
1 |
Offset(MQLONG型)※ |
オフセット |
0 |
MsgFlags(MQLONG型)※ |
メッセージフラグ |
MQMF_NONE |
OriginalLength(MQLONG型)※ |
登録元メッセージ長 |
MQOL_UNDEFINED |
概要
目的
MQMD構造体には,アプリケーション間でデータをやり取りするために必要な制御情報を記述します。この構造体はMQGET,MQPUTおよびMQPUT1命令の入出力用の引数です。
バージョン
MQMD構造体のバージョンには1および2があります。しかし,すべての環境でMQMD_VERSION_2がサポートされているわけではありません。複数の環境にアプリケーションを移植する場合は,使用するバージョンのMQMD構造体が,すべての環境でサポートされている必要があります。MQMD_VERSION_2以降の構造体にだけ存在するフィールドについては,そのことがフィールドの説明に記載されています。
サポートするプログラミング言語のCOPYファイルとINCLUDEファイルでは,最新バージョンのMQMD構造体が提供されます。ただし,Versionフィールドの初期値はMQMD_VERSION_1です。バージョン1の構造体にないフィールドを使用する場合は,アプリケーションで使用したいバージョンの番号をVersionフィールドに設定してください。
バージョン1の構造体宣言には,MQMD1型を使用できます。
文字セットおよびマシンコード
MQMD構造体のデータは,ローカルキューマネジャの文字セットおよびマシンコードに従います。それぞれ,キューマネジャのCodedCharSetId属性およびMQENC_NATIVEで指定します。TP1/Message Queue Accessのクライアントアプリケーションの場合,MQMD構造体はクライアントの文字セットおよびマシンコードにします。
送信側および受信側キューマネジャが使用する文字セットまたはマシンコードが異なる場合,MQMD構造体の中のデータは自動的に変換されます。アプリケーションがMQMD構造体を変換する必要はありません。
異なるバージョンのMQMD構造体の使用
バージョン1のMQMD構造体のアプリケーションデータの前にMQMDE構造体を追加すると,バージョン2のMQMD構造体と同じ機能になります。ただし,MQMDE構造体の全フィールドが初期値の場合,MQMDE構造体は省略できます。バージョン1のMQMD構造体とMQMDE構造体は次のように使用されます。
-
MQPUT命令およびMQPUT1命令で,アプリケーションがバージョン1のMQMD構造体を使用する場合,アプリケーションは,MQMDE構造体があることを示すために,MQMD構造体のFormatフィールドにMQFMT_MD_EXTENSIONを設定します。これによって,メッセージデータの前に,MQMDE構造体をオプションで追加できます。
- 注意事項
-
バージョン2のMQMD構造体に存在し,バージョン1のMQMD構造体に存在しない幾つかのフィールドは,MQPUT命令およびMQPUT1命令の入出力フィールドです。ただし,キューマネジャは,MQPUT命令およびMQPUT1命令からの出力では,MQMDE構造体の対応するフィールドへ値を返しません。アプリケーションが出力された値を必要とする場合は,バージョン2のMQMD構造体を使用しなければなりません。
-
MQGET命令でアプリケーションがバージョン1のMQMD構造体を指定すると,キューマネジャは返すメッセージの前にMQMDE構造体を追加します。ただし,MQMDE構造体の一つ以上のフィールドが初期値以外の値を持つ場合だけです。MQMD構造体のFormatフィールドはMQMDE構造体が存在することを示すために,MQFMT_MD_EXTENSIONとなります。
この構造体は,MQGET命令,MQPUT命令,およびMQPUT1命令の入出力用の引数です。
サポートされるすべてのプログラム言語について,MQMD構造体のデフォルト値はバージョン1構造体のデフォルト値と同じです。また,明示的なMQMD1構造体を利用できます(COBOL言語ではCOPYファイルのCMQMD1とCMQMD1V)。この構造体は,バージョン1のMQMD構造体とバージョン2のMQMD構造体を扱う必要があるアプリケーションのために提供されています。
メッセージが転送キュー上にある場合,MQMD構造体内のフィールドの一部が特定の値に設定されます。詳細については,この章の「MQXQH構造体 − 転送キューヘッダ」を参照してください。
メッセージコンテキスト
MQMD構造体の特定のフィールドには,メッセージコンテキストが含まれます。メッセージテキストには,識別コンテキストと登録元コンテキストがあります。
- 識別コンテキスト
-
該当するメッセージを最初に登録したアプリケーションに関係します。
- 登録元コンテキスト
-
該当するメッセージを最後に登録したアプリケーションに関係します。
これらの二つのアプリケーションは,同一のアプリケーションである場合と,同一のアプリケーションでない場合(例えば,メッセージがアプリケーションからアプリケーションへ転送される場合)があります。
識別コンテキストと登録元コンテキストには通常,上記のような意味があります。しかし実際には,MQMD構造体のコンテキストフィールドの内容は,メッセージ登録時に指定されたMQPMO_*_CONTEXTオプションによって決定されます。そのため,必ずしも上記のとおりではありません。アプリケーションの設計に依存します。
メッセージのコンテキストをまったく変更しないアプリケーションのクラスには,メッセージチャネルエージェント(MCA)があります。リモートキューマネジャからメッセージを受信するMCAは,MQPUTまたはMQPUT1命令にコンテキストオプションMQPMO_SET_ALL_CONTEXTを使用します。これによって受信側のMCAは,送信側のMCAからメッセージとともに送信されたメッセージコンテキストを,そのままの状態で保存できます。ただし,その結果として,登録元コンテキストはメッセージを最後に登録したアプリケーション(受信側MCA)に関係づけられないで,それ以前にメッセージを登録したアプリケーション(送信側アプリケーション自身を含む)に関係づけられます。
以降の説明では,上記に示した通常の方法でコンテキストフィールドが使用されている場合について説明します。メッセージのコンテキストの詳細については,マニュアル「TP1/Message Queue プログラム作成の手引」を参照してください。
フィールド
構造体を構成するフィールドについて,アルファベット順に説明します。
● AccountingToken(MQBYTE32型) 課金トークン
メッセージの識別コンテキストの一部です。メッセージコンテキストについては,この章の「MQMD構造体 − メッセージ記述子」の「概要」,およびマニュアル「TP1/Message Queue プログラム作成の手引」を参照してください。
アプリケーションが課金情報を必要とするときに使用できます。
この情報は,キューマネジャではビット列として扱われます。内容はチェックされません。キューマネジャによってこの情報が生成されるとき,次の値が設定されます。
-
1バイト目に,2バイト目以降に格納する課金情報の長さが設定されます。長さの範囲は0〜31で,2進数として格納されます。
-
2バイト目以降に,上記に示された長さで環境に応じた課金情報が設定されます。
-
上記以降のバイトには,2進数の0が設定されます。
MQPUT命令およびMQPUT1命令のPutMsgOpts引数でMQPMO_SET_IDENTITY_CONTEXTまたはMQPMO_SET_ALL_CONTEXTを指定した場合,入出力用フィールドとなります。MQPMO_SET_IDENTITY_CONTEXTもMQPMO_SET_ALL_CONTEXTも指定しなかった場合,このフィールドは入力時に無視されて出力専用のフィールドとなり,このフィールドは「\0」で埋められます。メッセージコンテキストおよびコンテキスト情報の制御については,マニュアル「TP1/Message Queue プログラム作成の手引」を参照してください。
MQPUT命令またはMQPUT1命令が成功すると,このフィールドには,転送されたメッセージのAccountingTokenが設定されます。メッセージにコンテキストがなかった場合,このフィールドは0となります。
MQGET命令では,出力用フィールドとなります。
このフィールドは,キューマネジャの文字セットの変換対象にはなりません。このフィールドは,文字列ではなく,ビット列として扱われます。
キューマネジャはこの情報を操作しません。この情報を課金目的で使用するときは,アプリケーションがそれを解釈してください。
次の定数値も使用できます。
- MQACT_NONE
-
課金トークンを指定しません。
この定数値は,2進数の0が設定されます。
C言語では,MQACT_NONE_ARRAYも定義されています。これは,MQACT_NONEと同じ値です。ただし,文字列ではなく文字の配列として定義されています。
このフィールドの長さは,MQ_ACCOUNTING_TOKEN_LENGTHに定義されています。
このフィールドの初期値はMQACT_NONEです。
● ApplIdentityData(MQCHAR32型) アプリケーション識別データ
メッセージの識別コンテキストの一部です。メッセージコンテキストについては,この章の「MQMD構造体 − メッセージ記述子」の「概要」,およびマニュアル「TP1/Message Queue プログラム作成の手引」を参照してください。
このフィールドでは,アプリケーションの組を定義します。また,メッセージまたは登録元に関する付加情報に使用できます。
この情報は,キューマネジャでは文字データとして扱われます。ただし,データの形式は規定されません。キューマネジャによってこの情報が生成されるとき,空白が設定されます。
MQPUT命令およびMQPUT1命令のPutMsgOpts引数でMQPMO_SET_IDENTITY_CONTEXTまたはMQPMO_SET_ALL_CONTEXTを指定した場合,入出力用フィールドとなります。このフィールドにヌル文字があった場合,ヌル文字以降の文字は,キューマネジャによって空白に置き換えられます。MQPMO_SET_IDENTITY_CONTEXTもMQPMO_SET_ALL_CONTEXTも指定しなかった場合,このフィールドは入力時に無視されて出力専用フィールドとなり,このフィールドは空白で埋められます。メッセージコンテキストおよびコンテキスト情報の制御については,マニュアル「TP1/Message Queue プログラム作成の手引」を参照してください。
MQPUT命令またはMQPUT1命令が成功すると,このフィールドには,転送されたメッセージのApplIdentityDataが設定されます。メッセージにコンテキストがなかった場合,このフィールドは空白で埋められます。
MQGET命令では,出力用フィールドとなります。
このフィールドの長さは,MQ_APPL_IDENTITY_DATA_LENGTHに定義されています。
このフィールドの初期値は,C言語ではヌル文字列です。そのほかのプログラミング言語では,32個の空白です。
● ApplOriginData(MQCHAR4型) 登録元データ
メッセージの登録元コンテキストの一部です。メッセージコンテキストについては,この章の「MQMD構造体 − メッセージ記述子」の「概要」,およびマニュアル「TP1/Message Queue プログラム作成の手引」を参照してください。
ApplOriginDataは,アプリケーションの組で定義する情報で,メッセージの登録元に関する付加情報として使用できます。例えば,適切な権限を持つアプリケーションが,識別データが信用できるかどうかを示すために設定できます。
この情報は,キューマネジャでは文字データとして扱われます。ただし,データの形式は規定されません。キューマネジャによってこの情報が生成されるとき,空白が設定されます。
MQPUT命令およびMQPUT1命令のPutMsgOpts引数でMQPMO_SET_ALL_CONTEXTを指定した場合,入出力用フィールドとなります。このフィールドのヌル文字以降の情報は破棄されます。ヌル文字以降の文字は,キューマネジャによって空白に置き換えられます。MQPMO_SET_ALL_CONTEXTを指定しなかった場合,このフィールドは入力時に無視されて出力専用フィールドとなり,このフィールドは空白で埋められます。
MQPUT命令またはMQPUT1命令が成功すると,このフィールドには転送されたメッセージのApplOriginDataが設定されます。メッセージにコンテキストがなかった場合,このフィールドは空白で埋められます。
MQGET命令では,出力用フィールドとなります。
このフィールドの長さは,MQ_APPL_ORIGIN_DATA_LENGTHに定義されています。
このフィールドの初期値は,C言語ではヌル文字列です。そのほかのプログラミング言語では,4個の空白です。
● BackoutCount(MQLONG型) ロールバック回数
トランザクション内のMQGET命令でメッセージが返されて,そのあとにロールバックした回数です。アプリケーションはこの回数によって,メッセージの内容が原因のエラーを検出できます。この回数には,MQGMO_BROWSE_*オプションを指定したMQGET命令は含まれません。
これは,MQGET命令の出力用フィールドです。MQPUT命令およびMQPUT1命令のときは無視されます。
このフィールドの初期値は0です。
● CodedCharSetId(MQLONG型) 文字セット識別子
メッセージデータの文字セット識別子です。
- 注意事項
-
命令引数であるMQMD構造体およびほかのMQデータ構造体の文字データは,キューマネジャの文字セットである必要があります。これは,キューマネジャのCodedCharSetId属性によって定義されている文字セットです。属性の詳細については,「3. オブジェクトの属性」の「キューマネジャの属性」を参照してください。
次の値が使用できます。
- MQCCSI_Q_MGR
-
キューマネジャの文字セット識別子
アプリケーションメッセージデータの文字データは,キューマネジャの文字セット(MQAサービス定義のmqa_local_ccsidオペランド指定値)を使用します。
MQPUTとMQPUT1命令では,キューマネジャはアプリケーションメッセージとともに設定するMQMD構造体のフィールドの値をキューマネジャの文字セット識別子(MQAサービス定義のmqa_local_ccsidオペランド指定値)に変更します。そのため,MQGET命令の際に,MQCCSI_Q_MGRという値が返されることはありません。
- MQCCSI_DEFAULT
-
デフォルトの文字セット識別子
StringフィールドのデータのCodedCharSetIdは,MQCFH構造体に先行するヘッダ構造体のCodedCharSetIdフィールドによって定義されます。MQCFH構造体がメッセージの先頭にある場合はMQMD構造体のCodedCharSetIdフィールドによって定義されます。
- MQCCSI_INHERIT
-
この構造体の文字セット識別子を引き継ぎます。
メッセージの文字データは,この構造体と同じ文字セットです。つまり,キューマネジャの文字セットです(MQMD構造体の場合だけ,MQCCSI_INHERITはMQCCSI_Q_MGRと同じ意味になります)。
メッセージで送信されるMQMD構造体のこの値を,キューマネジャはMQMD構造体の実際の文字セット識別子に変更します。エラーが発生しない場合,MQGET命令ではMQCCSI_INHERITは返されません。
MQMD構造体のPutApplTypeフィールドの値がMQAT_BROKERの場合,MQCCSI_INHERITは使用できません。
- MQCCSI_EMBEDDED
-
組み込みの文字セット識別子
メッセージ内の文字データの文字セットは,メッセージデータ自身に含まれている識別子の文字セットです。メッセージデータに組み込まれていて,データの異なる部分に適用される文字セット識別子は幾つあってもかまいません。この値は,幾つかの文字セットによるデータが混在したPCFメッセージでは必ず使用されます。PCFメッセージのフォーマット名はMQFMT_PCFです。
この値はMQPUT命令およびMQPUT1命令にだけ指定します。MQGET命令にこの値を指定すると,メッセージは変換されません。
MQPUTおよびMQPUT1命令では,メッセージとともに送信されるMQMD構造体中のMQCCSI_Q_MGRおよびMQCCSI_INHERITという値を,キューマネジャはキューマネジャの文字セット識別子と同じ値に変更します。しかし,MQPUTまたはMQPUT1命令に指定されたMQMD構造体は変更しません。指定された値について,ほかのチェックはありません。
メッセージを取り出すアプリケーションは,このフィールドが期待した値かどうかを比較します。期待した値以外の場合,アプリケーションはメッセージ中の文字データを変換する必要があります。
MQGMO_CONVERTオプションがMQGET命令で指定される場合,このフィールドは入出力用フィールドです。アプリケーションで指定された値は,メッセージデータの必要に応じて変換される文字セット識別子です。変換が成功した場合,または変換が不要の場合,値は変更されません。ただし,MQCCSI_Q_MGRおよびMQCCSI_INHERITが実際の値に変換される場合を除きます。変換が成功しなかった場合,MQGET命令後の値はアプリケーションに設定される未変換メッセージの文字セット識別子を表します。
MQGMO_CONVERTオプションがMQGET命令で指定されない場合,このフィールドは,MQGET命令の出力用フィールドです。また,MQPUT命令とMQPUT1命令の入力用フィールドです。
このフィールドの初期値はMQCCSI_Q_MGRです。
● CorrelId(MQBYTE24型) 相関識別子
MQGET命令では,取り出すメッセージの相関識別子を指定します。このフィールドの指定方法はMsgIdフィールドと同様です。
MQGET命令のGetMsgOpts引数でMQGMO_MSG_UNDER_CURSORオプションを指定した場合,このフィールドは無視されます。
MQGET命令が返されるとき,取り出したメッセージの相関識別子がCorrelIdフィールドに設定されます。
MQPUT命令およびMQPUT1命令では,アプリケーションは任意の相関識別子を指定できます。その値は,キューマネジャによってメッセージを取り出すアプリケーションに返されます。
MQPUTおよびMQPUT1命令にMQPMO_NEW_CORREL_IDオプションを指定する場合,登録したメッセージの相関識別子に,ユニークな相関識別子※がキューマネジャによって設定されます。
- 注※
-
キューマネジャによって生成される相関識別子(CorrelId)は,4バイトのプロダクト識別子と,それに続くプロダクト固有の文字列で構成されます。このCorrelIdは,EBCDICコードまたはASCIIコードのA〜Iの範囲の文字で始まっています。アプリケーションでCorrelIdを指定する場合は,キューマネジャによって生成される値との重複を避けるために,A〜I以外の文字で始まる文字列を指定してください。
報告が生成されるとき,登録元メッセージのReportフィールド(MQRO_COPY_MSG_ID_TO_CORREL_IDまたはMQRO_PASS_CORREL_ID)の方法で,CorrelIdが設定されます。アプリケーションが報告を生成するときも,同様の処理をする必要があります。
このフィールドは,キューマネジャの文字セットの変換対象にはなりません。このフィールドは,文字列ではなく,ビット列として扱われます。
次の定数値を使用できます。
- MQCI_NONE
-
相関識別子を指定しません。
この定数の値は,2進数の0です。
C言語では,MQCI_NONE_ARRAYも定義されています。これは,MQCI_NONEと同じ値です。ただし,文字列ではなく文字の配列として定義されています。
これは,MQGET命令の入出力用フィールドです。また,MQPUT命令とMQPUT1命令では,MQPMO_NEW_CORREL_IDの指定がない場合は入力用フィールドとなり,指定された場合は出力用フィールドとなります。
このフィールドの長さは,MQ_CORREL_ID_LENGTHに定義されています。
このフィールドの初期値はMQCI_NONEです。
● Encoding(MQLONG型) マシンコード形式
メッセージ内の数値データのマシンコード形式を指定します。ただし,MQMD構造体自身の数値データには適用されません。マシンコード形式は,2進整数,10進パック形式整数および浮動小数点の表記を定義します。
MQPUTまたはMQPUT1命令では,アプリケーションはデータに合った値をこのフィールドに設定する必要があります。キューマネジャは,フィールドが有効かどうかをチェックしません。次に示す特別な値が定義されます。
- MQENC_NATIVE
-
計算機固有のマシンコード形式
このマシンコード形式は,アプリケーションを実行するプログラミング言語と計算機に固有の値です。
- 注意事項
-
この定数の値は,プログラミング言語と環境に依存します。このため,アプリケーションは,実行する環境に合ったCOPYファイルとINCLUDEファイルを使用してコンパイルする必要があります。
メッセージを登録するアプリケーションは,通常,MQENC_NATIVEを指定します。メッセージを取り出すアプリケーションは,このフィールドがMQENC_NATIVEと等しいかどうかを比較します。等しくない場合は,アプリケーションはメッセージ中の数値データを変換する必要があります。MQGET命令の処理でキューマネジャがメッセージを変換するように指定するには,MQGMO_CONVERTオプションを使用できます。Encodingフィールドの指定方法については,「付録C マシンコード形式」を参照してください。
MQGMO_CONVERTオプションがMQGET命令で指定される場合,このフィールドは入出力用フィールドです。アプリケーションで指定された値は,メッセージデータの必要に応じて変換されるマシンコード形式です。変換が成功した場合,または変換が不要な場合,値は変更されません。変換が成功しなかった場合,MQGET命令後の値はアプリケーションに設定される未変換メッセージのマシンコード形式を表します。
MQGMO_CONVERTオプションがMQGET命令で指定されない場合,このフィールドは,MQGET命令の出力用フィールドです。また,MQPUT命令とMQPUT1命令の入力用フィールドです。
このフィールドの初期値はMQENC_NATIVEです。
● Expiry(MQLONG型) メッセージ保持時間
メッセージを登録するアプリケーションが指定する,1/10秒単位の時間です。この時間が経過する前にメッセージがあて先キューから取り出されないと,このメッセージは破棄できる状態になります。
あて先キューで時間が経過するごとに,この時間が減少します。リモートキューに登録した場合は,仲介するすべての転送キューで時間が減少します。また,転送時間が大きく影響する場合,MCAがこの時間を減少させます。必要に応じて,メッセージを次のキューへ進めるアプリケーションで同様に時間を減少させてください。ただし,メッセージ保持時間は概算で扱われるため,少しの時間では減少しません。
アプリケーションがMQGET命令でメッセージを取り出したとき,Expiryフィールドにはメッセージ保持時間の残りが示されます。
メッセージ保持時間が経過すると,キューマネジャによって破棄できる状態になります。破棄できる状態のメッセージは,検索MQGET命令や非検索MQGET命令が実行されると破棄されます。また,保持時間を経過したメッセージは,実行された命令が検索MQGET命令と非検索MQGET命令のどちらの場合も,返されません。例えば,MQGMO構造体のMatchOptionsフィールドの設定値がMQMO_NONEの非検索MQGET命令で,FIFO方式のキューから読み取りを実行するとします。この場合,終了していないメッセージが最初に出現するまでの,終了しているメッセージはすべて破棄されます。一方,優先順位方式のキューから同様の読み取りを実行した場合,終了していない最初のメッセージより先にキューに到着したメッセージのうち,優先順位が高いメッセージと優先順位が等しいメッセージが破棄されます。したがって,MQGET命令が成功した場合のExpiryフィールドの値は,0以上の数値またはMQEI_UNLIMITEDです。
メッセージをリモートキューへ登録した場合,メッセージがあて先キューに到着する前に転送キューに格納されている状態で保持時間が終了することがあります。その後,そのメッセージは破棄されます。
メッセージの報告オプションでMQRO_EXPIRATIONを指定した場合,保持時間終了でメッセージが破棄されたときに報告が生成されます。これらのオプションを指定しなかった場合,報告は生成されません。通常,代わりのメッセージが送られるため,保持時間が経過したあとは,そのメッセージは無関連のものとみなされます。
保持時間終了でメッセージを破棄するプログラムは,報告が要求されている場合,報告メッセージを通知する必要があります。
- 注意事項
-
-
TP1/Message Queueでは時間の減少を1/10秒単位の精度で実行しています。このフィールドに1〜9の値を指定した場合,0秒として扱います。このため,10未満の値を指定した場合,または相手システムから受信したメッセージ保持時間が10未満の値である場合,保持時間が経過したメッセージとして扱われます。
-
保持時間に0を指定して登録した場合,MQPUT命令またはMQPUT1命令は理由コードMQRC_EXPIRY_ERRORで失敗します。この場合,報告メッセージは生成されません。
-
保持時間が終了したメッセージはあとになるまで破棄されないため,それらのメッセージが取り出せない状態でキューに残ります。これらも,キューのメッセージ登録数として数えられます。この数え方は,トリガを起動する際のメッセージ登録数などのすべての場合に適用されます。
-
例外報告を要求している場合,保持時間が終了したときではなく,メッセージが実際に破棄されたときに例外報告が生成されます。
-
保持時間が終了したメッセージの破棄および例外報告の生成は,トランザクションの処理には含まれません。トランザクション内のMQGET命令の結果でメッセージが破棄された場合でも含まれません。
-
トランザクション内のMQGET命令で保持時間終了の際のメッセージを取り出したあとにトランザクションがロールバックした場合,再びメッセージを取り出す前に保持時間が終了することがあります。
-
同様に,MQGMO_LOCKオプションを指定したMQGET命令で保持時間終了間際のメッセージを排他状態にした場合,MQGMO_MSG_UNDER_CURSORオプションを指定したMQGET命令でメッセージを取り出す前に保持時間が終了することがあります。このとき,理由コードMQRC_NO_MSG_UNDER_CURSORがMQGET命令で返されます。
-
メッセージ保持時間がゼロよりも大きい問い合わせメッセージを取り出す場合,アプリケーションは応答メッセージを送信するときに次に示すどれかの処理を実行できます。
・残りの保持時間を問い合わせメッセージから応答メッセージにコピーする。
・応答メッセージ中の保持時間をゼロより大きい明示的な値に設定する。
・応答メッセージ中の保持時間をMQEI_UNLIMITEDに設定する。
実行される動作は,アプリケーションの設計に依存します。ただし,デッドレターキューにメッセージを登録するときのデフォルトでは,メッセージの残りの保持時間を保存し,減算を継続します。
-
トリガメッセージは,常にMQEI_UNLIMITEDオプションで生成されます。
-
Formatフィールドの名称がMQFMT_XMIT_Q_HEADERであるメッセージには,MQXQH構造体に二つ目のメッセージ記述子があります。通常,これらのメッセージは転送キューに格納されています。つまり,二つのExpiryフィールドがあります。この場合,次の点に注意してください。
注1
アプリケーションがリモートキューへメッセージを登録すると,キューマネジャによって転送キューへ格納されます。このとき,メッセージにMQXQHヘッダが付けられ,アプリケーションが指定した同じ値がExpiryフィールドへ設定されます。Formatの名称がMQFMT_XMIT_Q_HEADERのメッセージをアプリケーションが直接登録する場合,アプリケーションは二つのExpiryフィールドに同じ値を指定する必要はありません。キューマネジャは,MQXQH構造体のExpiryフィールドの値が正しいかどうかチェックしません。また,メッセージデータの長さが,MQXQH構造体を含むのに十分かどうかもチェックしません。
注2
Formatの名称がMQFMT_XMIT_Q_HEADERのメッセージが,キュー(通常キューまたは転送キュー)から取り出されたとき,キューマネジャは,キューで経過した時間を両方のExpiryフィールドの値から減算します。メッセージデータの長さがMQXQH構造体を含むのに十分ではない場合も,エラーは発生しません。
注3
メッセージを破棄できるかどうか判断するとき,キューマネジャによって「通常」のメッセージ記述子のExpiryフィールドが使用されます。MQXQH構造体のメッセージ記述子ではないため,注意が必要です。
注4
二つのExpiryフィールドの初期値が異なった場合,MQXQH構造体のExpiryフィールドの時間が経過しても,通常のメッセージ記述子のExpiryフィールドの値が0以上のときはメッセージを取り出せます。この場合,MQXQH構造体のExpiryフィールドには0が設定されます。
-
特殊な定数値として,次を指定できます。
このフィールドは,MQGET命令の出力用フィールドです。また,MQPUT命令とMQPUT1命令の入力用フィールドです。
このフィールドの初期値はMQEI_UNLIMITEDです。
● Feedback(MQLONG型) 報告メッセージ返答コード
このフィールドは,MQMT_REPORTタイプのメッセージで使用するもので,報告の性質を示します。メッセージタイプがMQMT_REPORTのときだけ有効です。
報告メッセージ返答コードは,次のように分けられます。
- MQFB_NONE
-
返答コードなし
- MQFB_SYSTEM_FIRST
-
システムが生成する返答コードの最小値
- MQFB_SYSTEM_LAST
-
システムが生成する返答コードの最大値
MQFB_SYSTEM_FIRSTからMQFB_SYSTEM_LASTまでのシステムが生成する返答コードの範囲には,後述する特殊な返答コード(MQFB_*)が含まれます。また,メッセージをあて先キューへ登録できなかったときに発生する理由コード(MQRC_*)も含まれます。
- MQFB_APPL_FIRST
-
アプリケーションが生成できる返答コードの最小値
- MQFB_APPL_LAST
-
アプリケーションが生成できる返答コードの最大値
報告メッセージを生成するアプリケーションは,システムの範囲の返答コード(MQFB_QUIT以外)を使用できません。ただし,キューマネジャやMCAが生成する報告メッセージをシミュレートする場合は例外です。
MQPUTまたはMQPUT1命令では,MQFB_NONE,システムの範囲またはアプリケーションの範囲の値を使用してください。この値は,MsgTypeフィールドの値に関係なくチェックされます。
一般的な返答コード:
- MQFB_COA
-
メッセージ到着確認
「Reportフィールド」のMQRO_COAオプションの説明を参照してください。
- MQFB_COD
-
メッセージ配布確認
「Reportフィールド」のMQRO_CODオプションの説明を参照してください。
- MQFB_EXPIRATION
-
メッセージ保持時間終了
保持時間が終了してもキューから削除されなかったため,メッセージは破棄されました。
- MQFB_PAN
-
肯定動作通知
- MQFB_NAN
-
否定動作通知
- MQFB_QUIT
-
アプリケーション終了指示
このコードは,実行中のアプリケーションプログラムの数を制御するために,負荷スケジューリングプログラムで使用できます。この返答コードのMQMT_REPORTタイプのメッセージが通知されると,そのアプリケーションに終了が指示されたことを意味します。ただし,この指示に従うかどうかはアプリケーションに任せられます。キューマネジャはそれを強要しません。
IMSブリッジの返答コード:
IMSブリッジが非ゼロのIMS-OTMAセンスコードを受け取るとき,センスコードを16進から10進に変換し,値MQFB_IMS_ERROR(300)を追加し,応答メッセージのFeedbackフィールドに格納します。そのため,IMS-OTMAエラーが発生した場合は,返答コードの値はMQFB_IMS_FIRST(301)からMQFB_IMS_LAST(399)の範囲になります。
IMSブリッジが生成する返答コードを次に示します。これらの値はTP1/Message Queueでは返りません。詳細については,IBM MQのマニュアルを参照してください。
CICSブリッジの返答コード:
CICSブリッジが生成する返答コードを次に示します。これらの値はTP1/Message Queueでは返りません。詳細については,IBM MQのマニュアルを参照してください。
理由コード:
例外報告の場合は,Feedbackフィールドに次の理由コードが設定されます。
- MQRC_PUT_INHIBITED
-
指定されたキューへの登録は禁止されています。
- MQRC_Q_FULL
-
キューが満杯です。
- MQRC_NOT_AUTHORIZED
-
アクセスの権限がありません。
- MQRC_Q_SPACE_NOT_AVAILABLE
-
キューに対応するディスクに空き領域がありません。
- MQRC_PERSISTENT_NOT_ALLOWED
-
キューは永続メッセージをサポートしていません。
- MQRC_MSG_TOO_BIG_FOR_Q_MGR
-
メッセージ長がリモートキューマネジャに許される値を超えています。
- MQRC_MSG_TOO_BIG_FOR_Q
-
メッセージ長がキューに定義された最大値を超えています。
このフィールドは,MQGET命令の出力用フィールドです。また,MQPUT命令とMQPUT1命令の入力用フィールドです。
このフィールドの初期値はMQFB_NONEです。
● Format(MQCHAR8型) フォーマット名
メッセージデータの性質を示す名称です。メッセージの送信側が受信側に示します。この名称には,キューマネジャの文字セットの文字を使用します。ただし,次に示す文字だけが使用できます。
-
英大文字のA〜Z
-
アラビア数字の0〜9
このほかの文字を使用すると,送信側と受信側のキューマネジャの間で,名称を変換できないことがあります。
この名称の余りは,空白で埋めます。または,ヌル文字で終了します。ヌル文字以降の文字は,空白として扱われます。先頭または中間に空白を含んだ名称は指定しないでください。MQGET命令では,キューマネジャによって,フィールドの余りが空白で埋められた名称が返されます。
使用文字の条件を満たしているかどうか,キューマネジャはチェックしません。
大文字,小文字および大文字小文字混合の「MQ」で始まる名称は,キューマネジャで定義されたことを意味します。ユーザ独自のフォーマットには,この文字で始まる名称を使用できません。キューマネジャのフォーマットは,次のとおりです。
- MQFMT_NONE
-
フォーマット名なし。
データの性質は定義されていません。これは,メッセージがキューから取り出されるときに,MQGMO_CONVERTオプションを使用してデータを変換できないことを意味します。
MQGET命令にMQGMO_CONVERTが指定され,メッセージ中のデータの文字セットまたはマシンコードがMsgDesc引数に指定されたものと異なる場合,メッセージが次に示す完了コードと理由コードとともに返されます(その他のエラーはないとします)。
-
メッセージの先頭にMQFMT_NONEデータがある場合は,完了コードMQCC_WARNINGと理由コードMQRC_FORMAT_ERRORが返されます。
-
MQFMT_NONEデータがメッセージの末尾にある場合(つまり,一つ以上のMQヘッダ構造体が先行している場合),完了コードMQCC_OKと理由コードMQRC_NONEが返されます。この場合,MQヘッダ構造体は,要求された文字セットとマシンコードに変換されます。
C言語では,MQFMT_NONE_ARRAYも定義されています。これは,MQFMT_NONEと同じ値です。ただし,文字列ではなく文字の配列として定義されています。
-
- MQFMT_ADMIN
-
コマンドサーバの問い合わせ/応答メッセージ
プログラマブルコマンドフォーマット(PCF)の問い合わせまたは応答メッセージです。
C言語では,MQFMT_ADMIN_ARRAYも定義されています。これは,MQFMT_ADMINと同じ値です。ただし,文字列ではなく文字の配列として定義されています。
- MQFMT_DEAD_LETTER_HEADER
-
デッドレターヘッダ
デッドレターヘッダ(MQDLH構造体)で始まるメッセージデータです。MQDLH構造体の後ろに,登録元メッセージのデータが続きます。登録元メッセージデータのフォーマット名は,MQDLH構造体のFormatフィールドに指定されています。MQDLH構造体の詳細については,この章の「MQDLH構造体 − デッドレターヘッダ」を参照してください。
FormatフィールドがMQFMT_DEAD_LETTER_HEADERのメッセージには,到着確認および配布確認報告は生成されません。
C言語では,MQFMT_DEAD_LETTER_HEADER_ARRAYも定義されています。これは,MQFMT_DEAD_LETTER_HEADERと同じ値です。ただし,文字列ではなく文字の配列として定義されています。
- MQFMT_DIST_HEADER
-
配布リストヘッダ
メッセージデータは配布リストヘッダ(MQDH構造体)で始まり,MQOR構造体およびMQPMR構造体レコードの配列を含んでいます。そのあとに,配布リストヘッダに追加する形式でデータが続きます。追加されたデータがある場合,そのフォーマットはMQDH構造体のFormatフィールドによって与えられます。MQDH構造体の詳細については,この章の「MQDH構造体 − 配布ヘッダ」を参照してください。MQGMO_CONVERTオプションがMQGET命令に指定されると,フォーマットのメッセージを変換できます。
C言語では,MQFMT_DIST_HEADER_ARRAYも定義されています。これは,MQFMT_DIST_HEADERと同じ値です。ただし,文字列ではなく文字の配列として定義されています。
- MQFMT_EVENT
-
イベントメッセージ
TP1/Message Queueでは意味がありません。
このオプションを指定しても,TP1/Message Queueの動作には影響しません。これは,アプリケーションの移植性を向上させるために定義されています。
発生したイベントを報告するメッセージキューイング機能のイベントメッセージです。イベントメッセージの構造は,プログラマブルコマンドの場合と同じです。
C言語では,MQFMT_EVENT_ARRAYも定義されています。これは,MQFMT_EVENTと同じ値です。ただし,文字列ではなく文字の配列として定義されています。
- MQFMT_MD_EXTENSION
-
メッセージ記述子の拡張
メッセージデータはメッセージ記述拡張子で始まり,ほかのデータ(通常はアプリケーションメッセージデータ)が続きます。MQMDE構造体に続くデータのフォーマット名,文字セットおよびマシンコード形式は,MQMDE構造体のFormatフィールド,CodedCharSetIdフィールド,およびEncodingフィールドによって与えられます。MQMDE構造体の詳細については,この章の「MQMDE構造体 − メッセージ記述子の拡張」を参照してください。このフォーマットのメッセージは,MQGET命令にMQGMO_CONVERTオプションを指定すると変換できます。
- MQFMT_PCF
-
プログラマブルコマンドフォーマット(PCF)のユーザ定義メッセージ
プログラマブルコマンドフォーマット(PCF)メッセージの構造に従ったユーザ定義のメッセージです。
MQGET命令でMQGMO_CONVERTオプションが指定されると,このフォーマットのメッセージは変換されます。
C言語では,MQFMT_PCF_ARRAYも定義されています。これは,MQFMT_PCFと同じ値です。ただし,文字列ではなく文字の配列として定義されています。
- MQFMT_REF_MSG_HEADER
-
参照メッセージヘッダ
メッセージデータは参照メッセージヘッダ(MQRMH構造体)で始まり,ほかのデータが続く場合もあります。MQRMH構造体に続くデータのフォーマット名,文字セットおよびマシンコード形式は,MQMDE構造体のFormatフィールド,CodedCharSetIdフィールド,およびEncodingフィールドによって与えられます。MQMDE構造体の詳細については,この章の「MQMDE構造体 − メッセージ記述子の拡張」を参照してください。このフォーマットのメッセージは,MQGET命令でMQGMO_CONVERTオプションを指定すると変換できます。
C言語では,定数MQFMT_REF_MSG_HEADER_ARRAYも定義されています。これは,MQFMT_REF_MSG_HEADERと同じ値です。ただし,文字列ではなく文字の配列として定義されています。
- MQFMT_STRING
-
文字だけのメッセージ
MQGET命令でMQGMO_CONVERTオプションが指定されると,このフォーマットのメッセージは変換されます。アプリケーションメッセージデータは,SBCS文字列(1バイト文字セット)でもDBCS文字列(2バイト文字セット)でもかまいません。
C言語では,MQFMT_STRING_ARRAYも定義されています。これは,MQFMT_STRINGと同じ値です。ただし,文字列ではなく文字の配列として定義されています。
- MQFMT_TRIGGER
-
トリガメッセージ
MQTM構造体で記述されるトリガメッセージです。MQTM構造体の詳細については,この章の「MQTM構造体 − トリガメッセージ」を参照してください。
C言語では,MQFMT_TRIGGER_ARRAYも定義されています。これは,MQFMT_TRIGGERと同じ値です。ただし,文字列ではなく文字の配列として定義されています。
- MQFMT_XMIT_Q_HEADER
-
転送キューヘッダ
転送キューヘッダ(MQXQH構造体)で始まるメッセージデータです。MQXQH構造体の後ろに,登録元メッセージのデータが続きます。登録元データのフォーマット名は,転送キューヘッダMQXQH構造体の中のMQMD構造体のFormatフィールドに指定されています。MQXQH構造体の詳細については,この章の「MQXQH構造体 − 転送キューヘッダ」を参照してください。
COA報告とCOD報告は,MQFMT_XMIT_Q_HEADERのFormatフィールドを持つメッセージに対しては生成されません。
C言語では,MQFMT_XMIT_Q_HEADER_ARRAYも定義されています。これは,MQFMT_XMIT_Q_HEADERと同じ値です。ただし,文字列ではなく文字の配列として定義されています。
このフィールドは,MQGET命令の出力用フィールドです。また,MQPUT命令とMQPUT1命令の入力用フィールドです。
このフィールドの長さは,MQ_FORMAT_LENGTHに定義されています。
このフィールドの初期値はMQFMT_NONEです。
● GroupId(MQBYTE24型) グループ識別子
物理メッセージが属する特定のメッセージグループまたは論理メッセージを識別するのに使用するバイト列です。GroupIdフィールドは,セグメント分割が許可されているときにも使用されます。ただし,すべてのケースでGroupIdフィールドはヌル以外の値であり,次に示すフラグの一つ以上がMsgFlagsフィールドに指定されていなければなりません。
-
MQMF_MSG_IN_GROUP
-
MQMF_LAST_MSG_IN_GROUP
-
MQMF_SEGMENT
-
MQMF_LAST_SEGMENT
-
MQMF_SEGMENTATION_ALLOWED
これらのフラグが一つも指定されない場合,GroupIdフィールドには特別なヌルの値であるMQGI_NONEが設定されます。
次の場合,アプリケーションによってMQPUT命令またはMQGET命令にGroupIdフィールドが設定される必要はありません。
-
MQPUT命令でMQPMO_LOGICAL_ORDERが指定された場合
-
MQGET命令でMQMO_MATCH_GROUP_IDが指定されない場合
報告メッセージではないメッセージに対して,MQPUT命令またはMQGET命令を使用するときには,上記のように命令を使用することをお勧めします。ただし,アプリケーションがさらに制御を必要としたり,MQPUT1命令を使用したりする場合,アプリケーションはGroupIdフィールドに適当な値が設定されていることを保証しなければなりません。
メッセージグループとセグメントはグループ識別子がユニークである場合だけ,正しく処理できます。このため,次に示す場合を除いては,アプリケーションによって自身のグループ識別子を生成しないでください。
-
MQPMO_LOGICAL_ORDERを指定すると,キューマネジャが自動的にグループの最初のメッセージまたは論理メッセージのセグメントにユニークなグループ識別子を生成します。その後,グループの残りのメッセージや論理メッセージのセグメントに対してそのグループ識別子を使用するので,アプリケーションが特別な処理をする必要がなくなります。MQPMO_LOGICAL_ORDERを指定できる場合は,指定することをお勧めします。
-
MQPMO_LOGICAL_ORDERを指定しない場合は,アプリケーションはグループメッセージまたは論理メッセージのセグメントに対する最初のMQPUT命令またはMQPUT1命令で,GroupIdフィールドにMQGI_NONEを指定して,キューマネジャにグループ識別子の生成を要求しなければなりません。出力値としてキューマネジャから返却されるグループ識別子は,グループの残りのメッセージや論理メッセージのセグメントに使用できます。メッセージグループにセグメント分割されたメッセージが含まれていれば,同一のグループ識別子がグループ内のすべてのセグメントとメッセージに使用されなければなりません。
MQPMO_LOGICAL_ORDERが指定されない場合,グループ内のメッセージや論理メッセージのセグメントはどんな順序(例:逆順)でも登録できますが,グループ識別子はそれらのメッセージに対して発行される最初のMQPUT命令またはMQPUT1命令で割り当てられなければなりません。
MQPUT命令またはMQPUT1命令で,キューマネジャはMQPMO構造体のMQPMO_LOGICAL_ORDERの表中に示される値を使用します。MQPUT命令またはMQPUT1命令で値を返す場合,オープンされているオブジェクトが単一のキューであり,配布リストではないときに,キューマネジャは,このフィールドにメッセージとともに送信される値を設定します。一方,オープンされているオブジェクトが配布リストのときは,フィールドの値は変更されません。配布リストがオープンされている場合,アプリケーションが生成されたグループ識別子を知る必要があるときは,GroupIdフィールドを含むMQPMR構造体を指定しなければなりません。
MQGET命令での入力について,キューマネジャはMQGMO構造体のMQGMO_LOGICAL_ORDERの表中に示される値を使用します。MQGET命令の出力について,キューマネジャはこのフィールドに取り出されたメッセージの値を設定します。
次の特別な値が定義されています。
- MQGI_NONE
-
グループ識別子を指定しません。
この定数の値は2進数の0です。
グループに属さない,かつ論理メッセージのセグメントではなく,かつセグメント分割もできないメッセージに使用されます。
C言語では,MQGI_NONE_ARRAYも定義されています。これはMQGI_NONEと同じ値です。ただし,文字列ではなく文字の配列として定義されています。
このフィールドの長さは,MQ_GROUP_ID_LENGTHに定義されています。
このフィールドの初期値はMQGI_NONEです。
このフィールドは,Versionフィールドの値がMQMD_VERSION_2以降の場合だけ有効です。
● MsgFlags(MQLONG型) メッセージフラグ
メッセージの属性を指定したり,処理を制御したりするフラグです。次のフラグがあります。
-
セグメンテーションフラグ
-
ステータスフラグ
-
デフォルトフラグ
セグメンテーションフラグ:
セグメンテーションフラグは,セグメント分割の際に使用されます。通常,メッセージがキューに対して大き過ぎる場合,キューへのメッセージ登録は失敗します。セグメント分割は,キューマネジャやアプリケーションがメッセージをセグメントと呼ばれる小さな部分に分割し,それぞれのセグメントを分離された物理メッセージとしてキューに配置する方法です。メッセージを取り出すアプリケーションは一つ一つセグメントを取り出すか,キューマネジャにセグメントをMQGET命令で返される単一のメッセージに組み立てさせることができます。メッセージを組み立てる場合は,MQGET命令でMQGMO_COMPLETE_MSGオプションを指定し,完全なメッセージを格納するのに十分なバッファを用意します。MQGMO_COMPLETE_MSGオプションの詳細は,この章の「MQGMO構造体 − メッセージ取り出しオプション」を参照してください。メッセージのセグメント分割は,送信キューマネジャ,中間のキューマネジャまたはあて先キューマネジャで発生する可能性があります。
メッセージのセグメント分割を制御するために,次の値の一つを指定できます。
- MQMF_SEGMENTATION_INHIBITED
-
セグメント分割の禁止
キューマネジャがメッセージをセグメント分割しないようにします。すでにセグメント分割されているメッセージが指定された場合,さらに小さなセグメントに分割することを防止できます。このフラグの初期値は2進数の0です。
- MQMF_SEGMENTATION_ALLOWED
-
セグメント分割の許可
キューマネジャがメッセージをセグメント分割することを指定します。すでにセグメント分割されているメッセージが指定された場合,さらに小さなセグメントに分割することを許可します。MQMF_SEGMENTATION_ALLOWEDはMQMF_SEGMENTまたはMQMF_LAST_SEGMENTの指定なしで指定できます。
キューマネジャは,必要に応じてセグメント,つまり,必要となるヘッダデータを加算したものがキューに当てはまるように,メッセージをセグメント分割します。キューマネジャは次のような処理をします。
-
ユーザ定義フォーマットを16バイトの倍数の境界で分割します。
-
MQFMT_STRING以外の組み込みフォーマットは,データの属性に適応した個所で分割します。ただし,キューマネジャは,メッセージをMQヘッダ構造体の中間で分割しません。なお,2番目以降のキューマネジャによって生成されたセグメントは,次のうちの一つでだけ始まります。
MQヘッダ構造体
アプリケーションメッセージデータの開始
アプリケーションメッセージデータの一部
-
MQFMT_STRINGでは,データの属性(SBCS,DBCS,SBCS/DBCS)が混在していても,それに関係なく分割されます。文字列にDBCSまたはSBCS/DBCSが混在している場合,セグメントがある文字セットから別の文字セットに変換できません。
-
キューマネジャによって,各セグメントのMQMD構造体のFormatフィールド,CodedCharSetIdフィールド,およびEncodingフィールドは,セグメントの先頭からそのデータを正確に表すように設定されます。フォーマット名は組み込みフォーマットまたはユーザ定義フォーマットです。
-
0より大きいOffsetフィールドを持つセグメントのMQMD構造体のReportフィールドは次のように調整されます。
それぞれの報告タイプについて,報告オプションがMQRO_*_WITH_DATAであるが,セグメントがユーザデータ,つまり,MQヘッダ構造体に続くデータの最初の100バイトをまったく含むことができない場合,報告オプションはMQRO_*に変更されます。
キューマネジャは上記の規則に従いますが,それ以外は適当な単位でメッセージを分割します。キューマネジャが特定のメッセージの分割を選択する方法については,何も仮定されません。
TP1/Message Queueでは,キューマネジャは,次に示すようにトランザクションの中でだけセグメント分割できます。
-
MQPUT命令またはMQPUT1命令がユーザ定義のトランザクションで実行される場合,そのトランザクションが使用されます。命令がセグメント分割の処理中に失敗した場合,キューマネジャはその呼び出しによって,キューに入れられたセグメントを削除します。命令がセグメント分割の処理中に失敗しても,トランザクションは正常にコミットされます。
-
命令がトランザクション外で実行された場合,キューマネジャはセグメント分割の処理をしません。ただし,メッセージのセグメント分割が必要な場合,MQRC_UOW_NOT_AVAILABLEの理由コードで失敗します。
セグメント分割されたメッセージのデータ変換に関しては,次に示す考慮が必要です。
-
送信側での変換が,MCAに指定されたとき,MCAは論理メッセージのセグメントではないメッセージだけを変換します。MCAはセグメント分割されたメッセージの変換をすることはありません。
セグメンテーションフラグはMQPUT命令およびMQPUT1命令の入力フラグです。また,MQGET命令の出力フラグです。MQGET命令では,キューマネジャがフラグの値をMQGMO構造体のSegmentationフィールドにも反映します。
このフラグの初期値はMQMF_SEGMENTATION_INHIBITEDです。
-
ステータスフラグ:
ステータスフラグは,物理メッセージがメッセージグループに属するか,論理メッセージのセグメントか,その両方か,またはどちらでもないのかを示すフラグです。次に示す一つ以上の値を,MQPUT命令またはMQPUT1命令で指定し,MQGET命令で返すことができます。
- MQMF_MSG_IN_GROUP
-
メッセージはグループのメンバです。
- MQMF_LAST_MSG_IN_GROUP
-
メッセージはグループの最終論理メッセージです。
このフラグが設定されると,キューマネジャはメッセージとともに送信されるMQMD構造体のコピーに,MQMF_MSG_IN_GROUPを設定します。ただし,アプリケーションがMQPUT命令またはMQPUT1命令で作成したMQMD構造体にあるこれらのフラグの設定は変更しません。
グループがただ一つの論理メッセージで構成されることがあります。この場合,MQMF_LAST_MSG_IN_GROUPが設定されますが,MsgSeqNumberフィールドの値は1となります。
- MQMF_SEGMENT
-
メッセージは論理メッセージのセグメントです。
MQMF_SEGMENTがMQMF_LAST_SEGMENTなしで指定された場合,MQヘッダ構造体が存在するときはその長さを除いたセグメントのアプリケーションメッセージデータ長は,小さくても1でなければなりません。長さが0の場合,MQPUT命令またはMQPUT1命令はMQRC_SEGMENT_LENGTH_ZEROとなり失敗します。
- MQMF_LAST_SEGMENT
-
メッセージは論理メッセージの最終セグメントです。
このフラグが設定されると,キューマネジャは,メッセージとともに送信されるMQMD構造体の複写に,MQMF_SEGMENTを設定します。ただし,アプリケーションがMQPUT命令またはMQPUT1命令で作成したMQMD構造体のフラグの設定は変更しません。
論理メッセージがただ一つのセグメントで構成されることがあります。この場合,MQMF_SEGMENTが設定されますが,Offsetフィールドの値は0となります。MQMF_LAST_SEGMENTが指定された場合,MQヘッダ構造体が存在するときはその長さを除いたセグメントのアプリケーションメッセージのデータ長が0であることもあります。
アプリケーションは,メッセージ登録時に,これらのフラグが正しく設定されることを保証しなければなりません。キューハンドルに対して,MQPMO_LOGICAL_ORDERを指定する,または以前のMQPUT命令で指定していた場合,フラグの設定はそのキューハンドルに対してキューマネジャの保持しているグループとセグメントの情報と一致していなければなりません。MQPMO_LOGICAL_ORDERが指定されたとき,キューハンドルに対して成功するMQPUT命令には,次の条件が適用されます。
-
現在のグループ,および現在の論理メッセージがない場合,フラグのすべてとその組み合わせが正しくなければなりません。
-
いったんMQMF_MSG_IN_GROUPを指定すると,MQMF_LAST_MSG_IN_GROUPを指定するまでMQMF_MSG_IN_GROUPを指定しなければなりません。この条件が満たされない場合,MQRC_INCOMPLETE_GROUPの理由コードで失敗します。
-
いったんMQMF_SEGMENTを指定すると,MQMF_LAST_SEGMENTを指定するまでMQMF_SEGMENTを指定しなければなりません。この条件が満たされない場合,MQRC_INCOMPLETE_MSGの理由コードで失敗します。
-
いったんMQMF_SEGMENTをMQMF_MSG_IN_GROUPなしに指定すると,MQMF_LAST_SEGMENTを指定するまでMQMF_MSG_IN_GROUPを指定しないでください。この条件が満たされない場合,MQRC_INCOMPLETE_MSGの理由コードで失敗します。
フラグの正しい組み合わせとさまざまなフィールドに使用される値については,この章の「MQPMO構造体 − メッセージ登録オプション」で,OptionsフィールドのMQPMO_LOGICAL_ORDERの表で示しています。
このフラグはMQPUT命令およびMQPUT1命令の入力フラグです。また,MQGET命令の出力フラグです。MQGET命令では,キューマネジャがフラグの値をMQGMO構造体のGroupStatusフィールドおよびSegmentStatusフィールドにも反映します。
-
デフォルトフラグ:
デフォルトフラグはメッセージのデフォルトの属性を示すために使用します。次の値は,メッセージがデフォルトの属性を持つことを示すために指定します。
- MQMF_NONE
-
メッセージフラグなし(メッセージ属性の初期値)。
セグメント分割が禁止されている,かつメッセージがグループにも属さない,かつ論理メッセージのセグメントでもないことを示しています。MQMF_NONEはプログラムの文書化の目的で定義されています。値としては0が定義されていますが,プログラムを文書化する以外の目的はありません。
MsgFlagsフィールドはサブフィールドに分割されています。詳細は「付録D 報告オプションとメッセージフラグ」を参照してください。
このフィールドの初期値はMQMF_NONEです。
このフィールドは,Versionフィールドの値がMQMD_VERSION_2以降の場合だけ有効です。
● MsgId(MQBYTE24型) メッセージ識別子
MQGET命令では,取り出すメッセージのメッセージ識別子を指定します。通常,MQGET命令に指定したメッセージ記述子の,MsgIdフィールドとCorrelIdフィールドに該当する最初のメッセージが,キューマネジャによって返されます。ただし,特殊な定数値として,MQMI_NONEおよびMQCI_NONEを使用できます。
-
MQGET命令のメッセージ識別子としてMQMI_NONEを指定すると,どんなメッセージ識別子でも該当します。
-
MQGET命令の相関識別子としてMQCI_NONEを指定すると,どんな相関識別子でも該当します。
なお,MQGET命令では,キューから特定のメッセージを選択して取り出すために,次に示すフィールドを使用できます。
-
MsgId
-
CorrelId
-
GroupId
-
MsgSeqNumber
-
Offset
MsgIdフィールドは,これらのフィールドの一つとして使用されます。
通常,MQGET命令は,キューにある次のメッセージを取り出します。特定のメッセージが必要な場合には,選択規準として一つまたは複数のフィールドを任意の組み合わせで指定すれば,目的のメッセージを取得します。
したがって,アプリケーションでは,一つ以上のフィールドを必要な値に設定した上で,MQGMO構造体のMatchOptionsフィールドに対応するMQMO_*一致オプションを設定します。これによって,フィールドを選択基準として使用できるようになり,フィールドに指定した値を持つメッセージだけが取り出しの対象になります。アプリケーションでMQMO_*一致オプションを設定しない場合は,MatchOptionsフィールドのデフォルトでは,メッセージ識別子および相関識別子の二つが選択規準として使用されます。
- 注意事項
-
選択規準に該当するメッセージは,キュー内で順次に検索されます。このため,選択規準がないときよりも,取り出しに時間が掛かります。特に,該当するメッセージを発見するまでに多くのメッセージを検索するほど,時間が掛かります。
MQGET命令のGetMsgOpts引数でMQGMO_MSG_UNDER_CURSORオプションを指定した場合,このフィールドは無視されます。
MQGET命令が返されるとき,取り出したメッセージのメッセージ識別子が,MsgIdフィールドに設定されます。
MQPUT命令およびMQPUT1命令でMQMI_NONEオプションを指定した場合,登録したメッセージのメッセージ記述子に,ユニークなメッセージ識別子※がキューマネジャによって設定されます。設定されたメッセージ識別子は,それを送信したアプリケーションにも,メッセージ記述子の一部として返されます。アプリケーションは,特定のメッセージに関する情報を記録するために,この値を使用できます。また,アプリケーションのほかの部分からの問い合わせに対する応答にも使用できます。
- 注※
-
キューマネジャによって生成されるメッセージ識別子(MsgId)は,4バイトのプロダクト識別子と,それに続くプロダクト固有の文字列で構成されます。このMsgIdは,EBCDICコードまたはASCIIコードのA〜Iの範囲の文字で始まっています。アプリケーションでMsgIdを指定する場合は,キューマネジャによって生成される値との重複を避けるために,A〜I以外の文字で始まる文字列を指定してください。
メッセージが配布リストに登録された場合,キューマネジャは要求されたとおりにユニークなメッセージ識別子を生成します。ただし,MQMI_NONEが指定されている場合でも,MQMD構造体のMsgIdフィールドの値は返されるときも変更されません。アプリケーションがキューマネジャの生成したメッセージ識別子を知る必要がある場合,アプリケーションはMsgIdフィールドを含むMQPMRレコードを提供しなければなりません。
送信するアプリケーションは,MQMI_NONE以外の定数値も,メッセージ識別子として指定できます。ただし,MQMI_NONE以外の値では,キューマネジャによって,ユニークなメッセージ識別子は生成されません。メッセージを転送するアプリケーションが,登録元メッセージのメッセージ識別子を引き渡すために,この機能を使用できます。
キューマネジャは,次の場合を除いて,このフィールドを使用しません。
-
上記に示したように,要求に応じてユニークな値を生成する場合
-
メッセージを取り出したアプリケーションに値を返す場合
-
報告オプションに依存して,このメッセージに関連した報告を生成し,かつ報告メッセージのCorrelIdフィールドに値を複写する場合
キューマネジャまたはMCAによって報告が生成されるとき,登録元メッセージのReportフィールド(MQRO_NEW_MSG_IDまたはMQRO_PASS_MSG_ID)に従ってMsgIdが設定されます。アプリケーションが報告を生成するときも,同様の処理をする必要があります。
MQPER_PERSISTENTのメッセージでは,キューマネジャが再開始しても,メッセージ記述子は失われません。
このフィールドは,キューマネジャの文字セットの変換対象にはなりません。このフィールドは,文字列ではなく,ビット列として扱われます。
次の定数値を使用できます。
- MQMI_NONE
-
メッセージ識別子を指定しません。
この定数の値は,2進数の0です。
C言語では,MQMI_NONE_ARRAYも定義されています。これは,MQMI_NONEと同じ値です。ただし,文字列ではなく文字の配列として定義されています。
このフィールドは,MQGET命令,MQPUT命令,およびMQPUT1命令の入出力用のフィールドです。
このフィールドの長さは,MQ_MSG_ID_LENGTHに定義されています。
このフィールドの初期値はMQMI_NONEです。
● MsgSeqNumber(MQLONG型) メッセージシーケンス番号
グループ内の論理メッセージのシーケンス番号を表すフィールドです。シーケンス番号は1から始まり,グループ内の新しい論理メッセージごとに1ずつ加算されます。最大値は999999999です。グループに属さない物理メッセージのシーケンス番号は1です。次の場合,MsgSeqNumberフィールドは,MQPUT命令またはMQPUT1命令でアプリケーションによって設定される必要はありません。
-
MQPMO_LOGICAL_ORDERがMQPUT命令で指定される場合
-
MQMO_MATCH_MSG_SEQ_NUMBERがMQGET命令で指定されない場合
報告メッセージではないメッセージに対して,MQPUT命令またはMQGET命令を使用するときには,上記のように命令を使用することをお勧めします。ただし,アプリケーションがさらに制御を必要としたり,MQPUT1命令を使用したりする場合,アプリケーションはシーケンス番号が適当な値に設定してあることを保証しなければなりません。
MQPUT命令またはMQPUT1命令で,キューマネジャはMQPMO構造体のMQPMO_LOGICAL_ORDERの表中に示される値を使用します。MQPUT命令またはMQPUT1命令で値を返す場合,キューマネジャは,このフィールドにメッセージとともに送信される値を設定します。
MQGET命令での入力について,キューマネジャはMQGMO構造体のMQGMO_LOGICAL_ORDERの表中に示される値を使用します。MQGET命令の出力について,キューマネジャはこのフィールドに取り出されたメッセージの値を設定します。
このフィールドの初期値は1です。
このフィールドは,Versionフィールドの値がMQMD_VERSION_2以降の場合だけ有効です。
● MsgType(MQLONG型) メッセージタイプ
メッセージの種類を示します。メッセージタイプは次のように分けられます。
次の値は,システムの範囲に定義されています。
- MQMT_DATAGRAM
-
非問い合わせメッセージ
応答を要求しないメッセージです。
- MQMT_REQUEST
-
問い合わせメッセージ
応答を要求するメッセージです。
応答を受け取りたいキューの名称を,ReplyToQフィールドに指定する必要があります。応答メッセージのReportフィールドには,応答メッセージのMsgIdとCorrelIdの設定方法が示されます。
- MQMT_REPLY
-
直前の問い合わせメッセージに対する応答メッセージ
直前の問い合わせメッセージ(MQMT_REQUEST)へ応答するメッセージです。このメッセージは,問い合わせメッセージのReplyToQフィールドのキューへ登録します。問い合わせメッセージのReportフィールドには,応答メッセージのMsgIdとCorrelIdの設定方法が示されます。
- 注意事項
-
キューマネジャは,問い合わせに対する応答の有無について関知しません。アプリケーションの責任で行ってください。
- MQMT_REPORT
-
報告メッセージ
各種の事象を報告するメッセージです。通常は,ほかのメッセージに関連して生成します。例えば,不正なデータを含んだ問い合わせメッセージを受信した場合などです。このメッセージは,登録元メッセージのメッセージ記述子のReplyToQフィールドのキューへ登録します。Feedbackフィールドには,報告の性質を示します。登録元メッセージのReportフィールドには,報告メッセージのMsgIdとCorrelIdの設定方法が示されます。
キューマネジャまたはMCAによって生成される報告メッセージは,FeedbackフィールドとCorrelIdフィールドに設定された値が使用されて,常にReplyToQのキューへ登録されます。
システムの範囲で上記以外の値は,MQIの次バージョン以降に定義されることがあります。それらの値は,MQPUT命令またはMQPUT1命令で,エラーが発生しないで受け付けられます。
また,アプリケーションで定義した値も使用できます。それらの値は,次の範囲で定義してください。
MQPUT命令およびMQPUT1命令のMsgTypeフィールドには,システムの範囲かアプリケーションの範囲の値を使用してください。使用しない場合,理由コードMQRC_MSG_TYPE_ERRORで命令は失敗します。
このフィールドは,MQGET命令の出力用フィールドです。また,MQPUT命令とMQPUT1命令の入力用フィールドです。
このフィールドの初期値はMQMT_DATAGRAMです。
● Offset(MQLONG型) オフセット
論理メッセージのデータ部の先頭からの物理メッセージデータのオフセットです。このデータをセグメントと呼びます。オフセットは0〜999999999の範囲です。論理メッセージのセグメントではない物理メッセージは,0のオフセットを持ちます。
次の場合,Offsetフィールドは,MQPUT命令またはMQGET命令でアプリケーションによって設定される必要はありません。
-
MQPMO_LOGICAL_ORDERがMQPUT命令で指定される場合
-
MQMO_MATCH_OFFSETがMQGET命令で指定されない場合
報告メッセージではないメッセージに対して,MQPUT命令またはMQGET命令を使用するときには,上記のように命令を使用することをお勧めします。ただし,アプリケーションが上記の条件に合わなかったり,MQPUT1命令を使用したりする場合,アプリケーションはオフセットが適当な値に設定してあることを保証しなければなりません。
MQPUT命令またはMQPUT1命令で,キューマネジャはMQPMO構造体のMQPMO_LOGICAL_ORDERの表中で示される値を使用します。MQPUT命令またはMQPUT1命令で値を返す場合,キューマネジャは,このフィールドにメッセージとともに送信される値を設定します。
論理メッセージのセグメントに対する報告メッセージでは,MQOL_UNDEFINEDではない場合に生成されるOriginalLengthフィールドは,キューマネジャによって保持されているセグメント情報に関するオフセット値の更新に使用されます。
MQGET命令での入力について,キューマネジャはMQGMO構造体のMQGMO_LOGICAL_ORDERの表中で示される値を使用します。MQGET命令の出力で,キューマネジャはこのフィールドに取り出されたメッセージの値を設定します。
このフィールドの初期値は0です。
このフィールドは,Versionフィールドの値がMQMD_VERSION_2以降の場合だけ有効です。
● OriginalLength(MQLONG型) 登録元メッセージ長
このフィールドはセグメントである報告メッセージにだけ関連します。報告メッセージが関連するメッセージセグメントの長さを指定します。セグメントによって構成されている論理メッセージの長さや,報告メッセージ中のデータの長さは指定しません。
- 注意事項
-
セグメントであるメッセージの報告メッセージを生成するときは,キューマネジャおよびメッセージチャネルエージェントが,元のメッセージからGroupId,MsgSeqNumber,OffsetおよびMsgFlagsフィールドを報告メッセージのMQMD構造体にコピーします。そのため,その報告メッセージもセグメントです。報告メッセージを生成するアプリケーションでは,同じことを実行し,OriginalLengthフィールドを正しく設定することをお勧めします。
次に示す特別な値があります。
このフィールドは,MQPUT命令やMQPUT1命令の入力用フィールドです。ただし,アプリケーションが指定する値は次に示す特定の場合にだけ受け入れられます。
-
登録されたメッセージがセグメントであり,報告メッセージでもある場合,キューマネジャはこのフィールドに指定された値を受け取ります。ただし,その値は次の条件を満たさなければなりません。
-
セグメントが最終セグメントではない場合,0より大きい
-
セグメントが最終セグメントの場合,0以上
-
メッセージのデータ長以上である
上記の条件が満たされない場合,MQRC_ORIGINAL_LENGTH_ERRORの理由コードで失敗します。
-
-
登録されるメッセージがセグメントであり,報告メッセージではない場合,キューマネジャはこのフィールドを無視して,アプリケーションメッセージ長を使用します。
-
そのほかの場合,キューマネジャはこのフィールドを無視してMQOL_UNDEFINEDを使用します。
OriginalLengthフィールドは,MQGET命令の出力用フィールドです。
このフィールドの初期値はMQOL_UNDEFINEDです。
このフィールドは,Versionフィールドの値がMQMD_VERSION_2以降の場合だけ有効です。
● Persistence(MQLONG型) メッセージ永続性
このフィールドは,システム障害後とキューマネジャを再度開始したあとにメッセージが残るかどうかを示します。MQPUT命令およびMQPUT1命令では,次のどれかの値を指定します。
- MQPER_PERSISTENT
-
永続メッセージにします。
メッセージはシステム障害後とキューマネジャを再度開始したあとも残ります。いったんメッセージが登録され,登録側のトランザクションがコミットされると(メッセージがトランザクションの一部として登録される場合),そのメッセージは補助記憶装置に保存されます。メッセージがキューから取り出され,取り出し側のトランザクションがコミットされる(メッセージがトランザクションの一部として取り出される場合)まで残ります。
永続メッセージをリモートキューへ送信するときは,格納・転送機構が使用されて,次のキューマネジャへ到着するまでメッセージが保持されます。
永続メッセージは,一時動的キューに登録できません。永続的動的キューおよび定義済みキューに登録できます。
- MQPER_NOT_PERSISTENT
-
非永続メッセージにします。
通常,メッセージはシステム障害後やキューマネジャを再度開始したあとに残りません。キューマネジャを再度開始するときにメッセージの完全なコピーが補助記憶装置で見つかった場合も適用されます。
- MQPER_PERSISTENCE_AS_Q_DEF
-
省略時のメッセージ永続性を使用します。
-
クラスタキューの場合,MQOPEN命令で指定するMQOD構造体のObjectQMgrNameフィールドの値によって,使用される永続性が異なります。
メッセージがシステム転送キューに登録されるときに,DefPersistence属性の値がPersistenceフィールドにコピーされます。その後,DefPersistence属性が変更されても,キューに登録済みのメッセージは影響を受けません。
MQOD構造体のObjectQMgrNameフィールドに空白を指定した場合
あて先キュー(クラスタキュー)に定義されたDefPersistence属性の値が,メッセージ永続性として使用されます。
ただし,MQOD構造体のObjectNameフィールドにリモートキューのローカル定義を指定して,あて先キュー(クラスタキュー)へ名称解決される場合は,システム転送キューに定義されたDefPersistence属性の値が,メッセージ永続性として使用されます。
MQOD構造体のObjectQMgrNameフィールドにあて先キューマネジャを指定した場合
システム転送キューに定義されたDefPersistence属性の値が,メッセージ永続性として使用されます。
-
クラスタキュー以外の場合,あて先キューマネジャがリモートキューマネジャであっても,ローカルキューマネジャに定義されたあて先キューのDefPersistence属性の値がメッセージ永続性として使用されます。
メッセージが登録されたとき,DefPersistence属性の値がPersistenceフィールドに設定されます。そのあとにDefPersistence属性の値を変更しても,すでに登録したメッセージには影響しません。
キューの実名をたどるまでに複数の定義がある場合(クラスタキューに名称解決される場合を除きます),最初に登録したキューの定義のこの属性が,省略時のメッセージ永続性になります。この属性は,次に示すオブジェクトに適用されます。
-
別名キュー
-
ローカルキュー
-
リモートキューのローカル定義
-
キューマネジャの別名
-
転送キュー(例えば,DefXmitQNameキュー)
-
永続メッセージと非永続メッセージを,同じキューに格納できます。
応答を返す場合,アプリケーションは通常,問い合わせメッセージの永続性を応答メッセージに使用します。
MQGET命令で返される値は,MQPER_PERSISTENTまたはMQPER_NOT_PERSISTENTのどちらかです。
このフィールドは,MQGET命令の出力用フィールドです。また,MQPUT命令とMQPUT1命令の入力用フィールドです。
このフィールドの初期値はMQPER_PERSISTENCE_AS_Q_DEFです。
● Priority(MQLONG型) メッセージ優先度
MQPUT命令およびMQPUT1命令では,0以上の値か,次に示す値を指定してください。
- MQPRI_PRIORITY_AS_Q_DEF
-
省略時のメッセージ優先度を使用します。
-
クラスタキューの場合,MQOPEN命令で指定するMQOD構造体のObjectQMgrNameフィールドの値によって,使用される優先度が異なります。
メッセージがシステム転送キューに登録されるときに,DefPriority属性の値がPriorityフィールドにコピーされます。その後,DefPriority属性が変更されても,キューに登録済みのメッセージは影響を受けません。
使用される優先度を次に示します。
MQOD構造体のObjectQMgrNameフィールドに空白を指定した場合
あて先キュー(クラスタキュー)に定義されたDefPriority属性の値が,メッセージ優先度として使用されます。
ただし,MQOD構造体のObjectNameフィールドにリモートキューのローカル定義を指定して,あて先キュー(クラスタキュー)へ名称解決される場合は,システム転送キューに定義されたDefPriority属性の値が,メッセージ優先度として使用されます。
MQOD構造体のObjectQMgrNameフィールドにあて先キューマネジャを指定した場合
システム転送キューに定義されたDefPriority属性の値が,メッセージ優先度として使用されます。
-
クラスタキュー以外の場合,あて先キューマネジャがリモートキューマネジャであっても,ローカルキューマネジャに定義されたあて先キューのDefPriority属性の値がメッセージ優先度として使用されます。
キューの実名をたどるまでに複数の定義がある場合(クラスタキューに名称解決される場合を除きます),最初に登録したキューの定義のこの属性が省略時のメッセージ優先度になります。この属性は,次に示すオブジェクトに適用されます。
-
別名キュー
-
ローカルキュー
-
リモートキューのローカル定義
-
キューマネジャの別名
-
転送キュー(例えば,DefXmitQNameキュー)
-
MQGET命令で返される値は,常に0以上です。MQPRI_PRIORITY_AS_Q_DEFは返されません。
ローカルキューマネジャに定義された最大値,つまり,キューマネジャのMaxPriority属性の値よりも大きな優先度でメッセージを登録した場合,メッセージは受け付けられますが,キューマネジャの優先度の最大値に置き換えられます。この場合,MQPUT命令およびMQPUT1命令は,完了コードMQCC_WARNING,理由コードMQRC_PRIORITY_EXCEEDS_MAXIMUMで終了します。ただし,Priorityフィールドには,メッセージを登録したアプリケーションで指定した値が残ります。
応答を返す場合,アプリケーションは通常,問い合わせメッセージの優先度を応答メッセージに使用します。また,MQPRI_PRIORITY_AS_Q_DEFを指定しても,アプリケーションを変更することなく優先度を調整できます。
このフィールドは,MQGET命令の出力用フィールドです。また,MQPUT命令とMQPUT1命令の入力用フィールドです。
このフィールドの初期値はMQPRI_PRIORITY_AS_Q_DEFです。
● PutApplName(MQCHAR28型) 登録アプリケーション名
メッセージの登録元コンテキストの一部です。メッセージコンテキストについては,この章の「MQMD構造体 − メッセージ記述子」の「概要」,およびマニュアル「TP1/Message Queue プログラム作成の手引」を参照してください。
MQPUT命令およびMQPUT1命令のPutMsgOpts引数でMQPMO_SET_ALL_CONTEXTを指定した場合,入出力用フィールドとなります。このフィールドのヌル文字以降の情報は破棄されます。ヌル文字以降の文字は,キューマネジャによって空白に置き換えられます。MQPMO_SET_ALL_CONTEXTを指定しなかった場合,このフィールドは入力時に無視されて出力専用フィールドとなり,このフィールドには実行中のユーザサーバ名が設定されます。
MQPUT命令またはMQPUT1命令が成功すると,このフィールドには,転送されたメッセージのPutApplNameが設定されます。メッセージにコンテキストがなかった場合,このフィールドは空白で埋められます。
MQGET命令では,出力用フィールドとなります。
このフィールドの長さは,MQ_PUT_APPL_NAME_LENGTHに定義されています。
このフィールドの初期値は,C言語ではヌル文字列です。そのほかのプログラミング言語では,28個の空白です。
● PutApplType(MQLONG型) 登録アプリケーションタイプ
メッセージの登録元コンテキストの一部です。メッセージコンテキストについては,この章の「MQMD構造体 − メッセージ記述子」の「概要」,およびマニュアル「TP1/Message Queue プログラム作成の手引」を参照してください。
次に示す標準のタイプを使用できます。また,ユーザが定義したタイプも使用できます。ただし,ユーザが定義できる値の範囲は,MQAT_USER_FIRSTからMQAT_USER_LASTまでです。
MQAT_OS2:OS/2またはプレゼンテーションマネジャアプリケーション
MQAT_WINDOWS:16ビットWindowsアプリケーション
MQAT_WLM:z/OSワークロードマネジャアプリケーション
- MQAT_DEFAULT
-
省略時のアプリケーションタイプ
アプリケーションが動作しているプラットフォームの,省略時のアプリケーションタイプです。TP1/Message Queueでは,MQAT_OPEN_TP1が仮定されます。
- 注意事項
-
この値は環境で定義する定数です。これによって,各プラットフォームに適切なヘッダ,インクルードファイル,およびコピーファイルを使用してコンパイルしたアプリケーションが実行できます。
- MQAT_UNKNOWN
-
未知のアプリケーションタイプ
この値は,アプリケーションタイプがわからないときに使用できます。ほかのコンテキスト情報があってもかまいません。
- MQAT_USER_FIRST
-
ユーザが定義できるアプリケーションタイプの最小値
- MQAT_USER_LAST
-
ユーザが定義できるアプリケーションタイプの最大値
また,次の特殊な値もあります。
- MQAT_NO_CONTEXT
-
メッセージにコンテキスト情報がありません。
この値は,メッセージにコンテキスト情報がない,つまり,MQPMO_*コンテキストオプションが指定されなかったときに,キューマネジャによって設定されます。
取り出したメッセージにコンテキスト情報があるかどうかを,PutApplTypeフィールドで調べることができます。ほかのどのコンテキストフィールドも空白ではない場合,MQPMO_SET_ALL_CONTEXTを使用したアプリケーションでは,PutApplTypeフィールドにMQAT_NO_CONTEXTを指定できません。
MQPUT命令およびMQPUT1命令のPutMsgOpts引数でMQPMO_SET_ALL_CONTEXTを指定した場合,入出力用フィールドとなります。MQPMO_SET_ALL_CONTEXTを指定しなかった場合,このフィールドは入力時に無視されて出力専用フィールドとなり,このフィールドには「15」が設定されます。「15」は,MQIヘッダファイル(cmqc.hまたはCMQV.cbl)に設定されている「MQAT_OPEN_TP1」または「MQAT-OPEN-TP1」の値です。cmqc.hまたはCMQV.cblを参照してください。
MQPUT命令またはMQPUT1命令が成功すると,このフィールドには,転送されたメッセージのPutApplTypeが設定されます。メッセージにコンテキストがなかった場合,MQAT_NO_CONTEXTが設定されます。
MQGET命令では,出力用フィールドとなります。
このフィールドの初期値はMQAT_NO_CONTEXTです。
● PutDate(MQCHAR8型) 登録日付
メッセージの登録元コンテキストの一部です。メッセージコンテキストについては,この章の「MQMD構造体 − メッセージ記述子」の「概要」,およびマニュアル「TP1/Message Queue プログラム作成の手引」を参照してください。
キューマネジャは,次の形式でこのフィールドを生成します。
- YYYYMMDD
-
YYYY:年(4けたの10進数)
MM:月(01〜12の10進数)
DD:日(01〜31の10進数)
PutDateフィールドとPutTimeフィールドには,グリニッジ標準時(GMT)を使用します。システムの時計を正しく設定してください。
トランザクション内からメッセージを登録した場合,コミットした日付ではなく,登録した日付になります。
MQPUT命令およびMQPUT1命令のPutMsgOpts引数でMQPMO_SET_ALL_CONTEXTを指定した場合,入出力用フィールドとなります。このフィールドの内容は,キューマネジャによってチェックされません。ただし,フィールド内のヌル文字以降の情報は破棄されます。ヌル文字以降の文字は,キューマネジャによって空白に置き換えられます。MQPMO_SET_ALL_CONTEXTを指定しなかった場合,このフィールドは入力時に無視されて出力専用フィールドとなり,このフィールドにはメッセージを登録した日付が設定されます。
MQPUT命令またはMQPUT1命令が成功すると,このフィールドには転送されたメッセージのPutDateが設定されます。メッセージにコンテキストがなかった場合,このフィールドは空白で埋められます。
MQGET命令では,出力用フィールドとなります。
このフィールドの長さは,MQ_PUT_DATE_LENGTHに定義されています。
このフィールドの初期値は,C言語ではヌル文字列です。そのほかのプログラミング言語では,8個の空白です。
● PutTime(MQCHAR8型) 登録時刻
メッセージの登録元コンテキストの一部です。メッセージコンテキストについては,この章の「MQMD構造体 − メッセージ記述子」の「概要」,およびマニュアル「TP1/Message Queue プログラム作成の手引」を参照してください。
キューマネジャは,次の形式でこのフィールドを生成します。
- HHMMSSTH
-
HH:時(00〜23の10進数)
MM:分(00〜59の10進数)
SS:秒(00〜59の10進数)
T:1/10秒 (0〜9の10進数)
H:1/100秒(0〜9の10進数)
PutDateフィールドとPutTimeフィールドには,グリニッジ標準時(GMT)を使用します。システムの時計を正しく設定してください。
トランザクション内からメッセージを登録した場合,コミットした時刻ではなく登録した時刻になります。
MQPUT命令およびMQPUT1命令のPutMsgOpts引数でMQPMO_SET_ALL_CONTEXTを指定した場合,入出力用フィールドとなります。このフィールドの内容は,キューマネジャによってチェックされません。ただし,フィールド内のヌル文字以降の情報は破棄されます。ヌル文字以降の文字は,キューマネジャによって空白に置き換えられます。MQPMO_SET_ALL_CONTEXTを指定しなかった場合,このフィールドは入力時に無視されて出力専用フィールドとなり,このフィールドにはメッセージを登録した時間が設定されます。
MQPUT命令またはMQPUT1命令が成功すると,このフィールドには転送されたメッセージのPutTimeが設定されます。メッセージにコンテキストがなかった場合,このフィールドは空白で埋められます。
MQGET命令では,出力用フィールドとなります。
このフィールドの長さは,MQ_PUT_TIME_LENGTHに定義されています。
このフィールドの初期値は,C言語ではヌル文字列です。そのほかのプログラミング言語では,8個の空白です。
● ReplyToQ(MQCHAR48型) 応答キュー名
アプリケーションがMQMT_REPLYタイプとMQMT_REPORTタイプのメッセージを取り出すキューの名称です。ReplyToQMgrのキューマネジャに定義されたキューのローカル名称です。
MQPUT命令およびMQPUT1命令では,MsgTypeフィールドがMQMT_REQUESTのとき,またはReportフィールドで報告を要求したときに,このフィールドに空白を指定できません。ただし,ここで指定した値は,どんなタイプのメッセージの場合でも,それを取り出すアプリケーションに返されます。
ReplyToQMgrフィールドが空白の場合,ローカルキューマネジャは,ReplyToQと同じ名称のキューの定義を参照します。この名称のリモートキューのローカル定義があれば,転送されるメッセージのReplyToQの名称は,リモートキューのローカル定義のRemoteQName属性で置き換えられます。この値は,MQGET命令でメッセージを取り出すアプリケーションに,メッセージ記述子の一部として返されます。リモートキューのローカル定義がない場合,ReplyToQフィールドは変更されません。
名称を指定するとき,余りを空白で埋めることができます。また,最初のヌル文字以降の文字は,空白として扱われます。ただし,キューの名称の規則に従っているかどうかはチェックされません。これは,転送されるメッセージのReplyToQの名称が置き換えられた場合も同様です。名称を指定したかどうかが,必要時にチェックされるだけです。
応答キューが必要ない場合,ReplyToQフィールドには,次のどれかを指定してください。ただし,チェックはされません。
-
空白
-
ヌル文字列(C言語の場合)
-
ヌル文字で終了する幾つかの空白(C言語の場合)
このフィールドは,左詰めで指定します。
MQGET命令では,この名称は,フィールドの余りが常に空白で埋められて返されます。
報告を要求したメッセージが配布されなかった場合で,報告メッセージも指定したキューに登録されなかったときは,登録元メッセージも報告メッセージもデッドレターキューに転送されます。詳細については,「3. オブジェクトの属性」の「キューマネジャの属性」でDeadLetterQName属性の説明を参照してください。
このフィールドは,MQGET命令の出力用フィールドです。また,MQPUT命令とMQPUT1命令の入力用フィールドです。
このフィールドの長さは,MQ_Q_NAME_LENGTHに定義されています。
このフィールドの初期値は,C言語ではヌル文字列です。そのほかのプログラミング言語では,48個の空白です。
● ReplyToQMgr(MQCHAR48型) 応答キューマネジャ名
応答メッセージまたは報告メッセージを送信する先の,キューマネジャ名です。ReplyToQフィールドの値は,このキューマネジャに定義されたローカルキューの名称です。
ReplyToQMgrフィールドが空白の場合,ローカルキューマネジャは,ReplyToQと同じ名称のキューの定義を参照します。この名称のリモートキューのローカル定義があれば,転送されるメッセージのReplyToQMgrの名称は,リモートキューのローカル定義のRemoteQMgrName属性の値で置き換えられます。この値は,MQGET命令でメッセージを取り出すアプリケーションに,メッセージ記述子の一部として返されます。リモートキューのローカル定義がない場合,ReplyToQMgrフィールドはローカルキューマネジャの名称になります。
名称を指定するとき,余りを空白で埋めることができます。また,最初のヌル文字以降の文字は,空白として扱われます。ただし,キューマネジャの名称の規則に従っているかどうかはチェックされません。また,そのキューマネジャ名が送信先のキューマネジャで認識されているかどうかも,チェックされません。これは,転送されるメッセージのReplyToQMgrの名称が置き換えられた場合も同様です。オブジェクトの命名規則については,マニュアル「TP1/Message Queue プログラム作成の手引」を参照してください。
応答キューが必要ない場合,ReplyToQMgrフィールドは,次のどれかを指定してください。ただし,チェックはされません。
-
空白
-
ヌル文字列(C言語の場合)
-
ヌル文字で終了する幾つかの空白(C言語の場合)
このフィールドは,左詰めで指定します。
MQGET命令では,この名称は,フィールドの余りが常に空白で埋められて返されます。
このフィールドは,MQGET命令の出力用フィールドです。また,MQPUT命令とMQPUT1命令の入力用フィールドです。
このフィールドの長さは,MQ_Q_MGR_NAME_LENGTHに定義されています。
このフィールドの初期値は,C言語ではヌル文字列です。そのほかのプログラミング言語では,48個の空白です。
● Report(MQLONG型) 報告オプション
報告とは,登録元メッセージに関連して発生した各種の事象についてアプリケーションに通知するためのメッセージです。Reportフィールドを使用すると,登録元アプリケーションは次のことを指定できます。
-
どんな種類の報告メッセージが必要かを指定します。
-
報告メッセージ内にアプリケーションデータを組み込むかどうかを指定します。
-
報告メッセージまたは応答メッセージに,どのようにしてメッセージ識別子や相関識別子を設定するかを指定します。この場合は,報告と応答の両方で,Reportフィールドを使用できます。
次に示す6種類の報告から,一つまたは複数を指定できます。指定しなくてもかまいません。
-
例外
-
保持時間終了
-
到着確認
-
配布確認
-
肯定動作の通知
-
否定動作の通知
それぞれの種類の報告では,報告メッセージ内にアプリケーションデータを組み込むか組み込まないかの,どちらかを指定してください。複数の種類の報告メッセージが必要なとき,または,MsgIdとCorrelIdをどのように生成するかを制御したいときは,次のどちらかに従ってください。
-
それぞれを加算します。このとき,同じ値は2回以上加算しないでください。
-
プログラミング言語がビット演算をサポートしている場合,それぞれのビット論理和を取ります。
なお,オプションおよびその指定方法の一覧については,「付録A 命令および引数の一覧」を参照してください。
例外報告オプション:
- MQRO_EXCEPTION
-
例外報告を要求します。
例外報告は,メッセージをほかのキューマネジャへ送信した場合で,あて先キューに到着しなかったときに,MCAによって生成されます。例えば,次のような場合です。
-
あて先キューまたは仲介する転送キューが満杯だった場合
-
キューに対してメッセージが長過ぎた場合
報告メッセージが生成されるのは,到着しなかったメッセージが,デッドレターキューに転送されたときだけです。デッドレターキューに転送されなかった場合,または,デッドレターキューを定義していなかった場合は,メッセージは転送キュー内に残ります。例外報告は生成されません。
MQPUT命令またはMQPUT1命令で返される理由コードで,直後にエラーが判明する場合は,例外報告は生成されません。
また,アプリケーションも例外報告を生成できます。この場合,取り出したメッセージを処理できないことを報告します。例えば,計算機使用料の貸方の限度額を超過したときなどに,メッセージを処理できないことを報告します。
登録元メッセージのデータは,報告メッセージ内に組み込まれません。
次に示すオプションは,MQRO_EXCEPTIONオプションと同時に指定できません。
-
MQRO_EXCEPTION_WITH_DATA
-
MQRO_EXCEPTION_WITH_FULL_DATA
-
- MQRO_EXCEPTION_WITH_DATA
-
例外報告をデータ付きで要求します。
報告メッセージ内に登録元メッセージのアプリケーションデータが組み込まれることを除けば,MQRO_EXCEPTIONと同様です。登録元メッセージに一つ以上のMQヘッダ構造体がある場合,それらの構造体はアプリケーションデータの100バイトとともに,報告メッセージに格納されます。
次に示すオプションは,MQRO_EXCEPTION_WITH_DATAオプションと同時に指定できません。
-
MQRO_EXCEPTION
-
MQRO_EXCEPTION_WITH_FULL_DATA
-
- MQRO_EXCEPTION_WITH_FULL_DATA
-
例外報告をデータ付きで要求します。
報告メッセージ内に,登録元メッセージのアプリケーションデータが組み込まれることを除けば,MQRO_EXCEPTIONと同様です。報告メッセージ内にアプリケーションデータをすべて組み込みます。
次に示すオプションは,MQRO_EXCEPTION_WITH_FULL_DATAオプションと同時に指定できません。
-
MQRO_EXCEPTION
-
MQRO_EXCEPTION_WITH_DATA
-
保持時間終了報告オプション:
- MQRO_EXPIRATION
-
保持時間終了報告を要求します。
保持時間終了報告は,メッセージ保持時間(Expiryフィールド)を終了したメッセージが,アプリケーション配布前に破棄されたときに生成されます。この報告は,リモートキューマネジャによって生成されます。MQRO_EXCEPTIONオプションを指定していても,MQRO_EXPIRATIONオプションを指定しないと,メッセージ保持時間切れが原因でメッセージが破棄されても報告メッセージは生成されません。
登録元メッセージのデータは,報告メッセージ内に組み込まれません。
次に示すオプションは,MQRO_EXPIRATIONオプションと同時に指定できません。
-
MQRO_EXPIRATION_WITH_DATA
-
MQRO_EXPIRATION_WITH_FULL_DATA
-
- MQRO_EXPIRATION_WITH_DATA
-
保持時間終了報告をデータ付きで要求します。
報告メッセージ内に登録元メッセージのアプリケーションデータが組み込まれることを除けば,MQRO_EXPIRATIONと同様です。登録元メッセージに一つ以上のMQヘッダ構造体がある場合,それらの構造体は100バイトのアプリケーションデータとともに,報告メッセージに格納されます。
次に示すオプションは,MQRO_EXPIRATION_WITH_DATAオプションと同時に指定できません。
-
MQRO_EXPIRATION
-
MQRO_EXPIRATION_WITH_FULL_DATA
-
- MQRO_EXPIRATION_WITH_FULL_DATA
-
保持時間終了報告をデータ付きで要求します。
報告メッセージ内に登録元メッセージのアプリケーションデータが組み込まれることを除けば,MQRO_EXPIRATIONと同様です。
次に示すオプションは,MQRO_EXPIRATION_WITH_FULL_DATAオプションと同時に指定できません。
-
MQRO_EXPIRATION
-
MQRO_EXPIRATION_WITH_DATA
-
到着確認報告オプション:
- MQRO_COA
-
到着確認報告を要求します。
到着確認報告は,あて先キューにメッセージが到着したときに生成されます。この報告は,あて先キューを管理するキューマネジャによって生成されます。
トランザクション内からメッセージを登録した場合で,あて先キューがローカルキューのときは,到着確認報告メッセージはトランザクションがコミットしたときに有効になります。
メッセージ記述子のFormatフィールドがMQFMT_DEAD_LETTER_HEADERの場合,到着確認報告は生成されません。これによって,配布できないでデッドレターキューへ転送されたメッセージのときに,到着確認報告が生成されるのを防ぎます。
登録元メッセージのデータは,報告メッセージ内に組み込まれません。
次に示すオプションは,MQRO_COAオプションと同時に指定できません。
-
MQRO_COA_WITH_DATA
-
MQRO_COA_WITH_FULL_DATA
-
- MQRO_COA_WITH_DATA
-
到着確認報告をデータ付きで要求します。
報告メッセージ内に登録元メッセージのアプリケーションデータが組み込まれることを除けば,MQRO_COAと同様です。登録元メッセージに一つ以上のMQヘッダ構造体がある場合,それらの構造体は100バイトのアプリケーションデータとともに,報告メッセージに格納されます。
次に示すオプションは,MQRO_COA_WITH_DATAオプションと同時に指定できません。
-
MQRO_COA
-
MQRO_COA_WITH_FULL_DATA
-
- MQRO_COA_WITH_FULL_DATA
-
到着確認報告をデータ付きで要求します。
報告メッセージ内に登録元メッセージのアプリケーションデータが含まれることを除けば,MQRO_COAと同様です。
次に示すオプションは,MQRO_COA_WITH_FULL_DATAオプションと同時に指定できません。
-
MQRO_COA
-
MQRO_COA_WITH_DATA
-
配布確認報告オプション:
- MQRO_COD
-
配布確認報告を要求します。
配布確認報告は,アプリケーションによってメッセージが取り出され,キューから削除されたときに生成されます。この報告は,キューマネジャによって生成されます。
トランザクション内からメッセージが取り出された場合,配布確認報告メッセージは,そのトランザクションの処理の一部として生成されます。このため,トランザクションがコミットするまでは,報告は有効になりません。トランザクションがロールバックした場合,報告メッセージは通知されません。
メッセージ記述子のFormatフィールドがMQFMT_DEAD_LETTER_HEADERの場合,配布確認報告は生成されません。これによって,配布できないでデッドレターキューへ転送されたメッセージのときに,配布確認報告が生成されるのを防ぎます。
登録元メッセージのデータは,報告メッセージ内に組み込まれません。
次に示すオプションは,MQRO_CODオプションと同時に指定できません。
-
MQRO_COD_WITH_DATA
-
MQRO_COD_WITH_FULL_DATA
-
- MQRO_COD_WITH_DATA
-
配布確認報告をデータ付きで要求します。
報告メッセージ内に登録元メッセージのアプリケーションデータが組み込まれることを除けば,MQRO_CODと同様です。元のメッセージに一つ以上のMQヘッダ構造体がある場合,それらの構造体は100バイトのアプリケーションデータとともに,報告メッセージに格納されます。
MQGMO_ACCEPT_TRUNCATED_MSGオプションを使用して,登録元データの後部が切り捨てられていた場合,報告メッセージデータの長さは切り捨てられた長さになります。
次に示すオプションは,MQRO_COD_WITH_DATAオプションと同時に指定できません。
-
MQRO_COD
-
MQRO_COD_WITH_FULL_DATA
-
- MQRO_COD_WITH_FULL_DATA
-
配布確認報告をデータ付きで要求します。
報告メッセージ内に登録元メッセージのアプリケーションデータが組み込まれることを除けば,MQRO_CODと同様です
MQGMO_ACCEPT_TRUNCATED_MSGオプションを使用して登録元データの後部が切り捨てられていた場合,報告メッセージデータの長さは切り捨てられた長さになります。
次に示すオプションは,MQRO_COD_WITH_FULL_DATAオプションと同時に指定できません。
-
MQRO_COD
-
MQRO_COD_WITH_DATA
-
肯定動作または否定動作の報告オプション:
受信アプリケーションが肯定動作または否定動作の報告メッセージの送信を要求するために,次に示すオプションを指定できます。
- MQRO_PAN
-
肯定動作を通知する報告が要求されました。
この形式の報告は,メッセージを取り出し,そのメッセージに対して動作するアプリケーションによって生成されます。メッセージで要求された動作は成功したことを示します。報告を生成するアプリケーションは,どんなデータでも報告の中に含めるかどうか決定できます。
メッセージを取り出すアプリケーションにこの要求を通知する以外に,キューマネジャはこのオプションに基づいて何もしません。報告は,取り出すアプリケーションの責任で生成してください。
- MQRO_NAN
-
否定動作を通知する報告が要求されました。
この形式の報告は,メッセージを取り出し,そのメッセージに対して動作するアプリケーションによって生成されます。メッセージで要求された動作は成功しなかったことを示します。報告を生成するアプリケーションは,どんなデータでも報告の中に含めるかどうか決定できます。
メッセージを取り出すアプリケーションにこの要求を通知する以外に,キューマネジャはこのオプションに基づいて何もしません。報告は,取り出すアプリケーションの責任で生成してください。
肯定動作に対応する条件か,否定動作に対応する条件か決めるのはアプリケーションの責任です。しかし,もし要求が部分的に実行されたのであれば,PAN報告よりもNAN報告を生成することをお勧めします。また,すべての可能な条件は,肯定動作または否定動作の両方に対応させるのでなく,どちらかに対応させることをお勧めします。
MsgId設定用オプション:
報告メッセージまたは応答メッセージに,どのようにMsgIdを設定するかを次のオプションで指定できます。
- MQRO_NEW_MSG_ID
-
メッセージ識別子を付け直します。
これは,メッセージ識別子を指定しないときのオプションです。このメッセージの結果で報告または応答が生成されたとき,報告メッセージまたは応答メッセージのメッセージ識別子は新しく付け直されます。
- MQRO_PASS_MSG_ID
-
メッセージ識別子を引き渡します。
このメッセージの結果で報告または応答が生成されたとき,このメッセージのMsgIdが報告メッセージまたは応答メッセージのMsgIdフィールドへ複写されます。
このオプションを指定しなかった場合,MQRO_NEW_MSG_IDが仮定されます。
CorrelId設定用オプション:
報告メッセージまたは応答メッセージにどのようにCorrelIdを設定するかを,次のオプションで指定できます。
- MQRO_COPY_MSG_ID_TO_CORREL_ID
-
メッセージ識別子の値を複写します。
これは,相関識別子を指定しないときのオプションです。このメッセージの結果で報告または応答が生成されたとき,このメッセージのメッセージ識別子の値が報告メッセージまたは応答メッセージのCorrelIdフィールドへ複写されます。
- MQRO_PASS_CORREL_ID
-
相関識別子を引き渡します。
このメッセージの結果で報告または応答が生成されたとき,このメッセージのCorrelIdが,報告メッセージまたは応答メッセージのCorrelIdフィールドへ複写されます。
このオプションを指定しなかった場合,MQRO_COPY_MSG_ID_TO_CORREL_IDが仮定されます。
応答または報告を生成するサーバでは,登録元メッセージにMQRO_PASS_CORREL_IDおよびMQRO_PASS_MSG_IDオプションが指定されているかどうか,確認する必要があります。指定されていれば,オプションの説明の記述に従ってください。指定されていなければ,省略時の記述に従ってください。
後処理オプション:
アプリケーションから登録したメッセージをあて先キューに登録できない場合,次に示すオプションのどちらかを指定して,メッセージの後処理を制御できます。これらのオプションが適用されるのは,送信側アプリケーションが要求した場合に,例外報告メッセージが生成されるときだけです。アプリケーションは後処理オプションを,例外報告の要求とは無関係に設定できます。
- MQRO_DEAD_LETTER_Q
-
メッセージをデッドレターキューに登録します。
これはデフォルトの動作であり,あて先キューに登録できないメッセージはデッドレターキューに登録されることを示します。送信側からの要求がある場合には,例外報告メッセージが生成されます。
- MQRO_DISCARD_MSG
-
TP1/Message Queueでは意味がありません。
メッセージを廃棄します。
あて先キューに登録できないメッセージを廃棄することを示します。送信側からの要求がある場合には,例外報告メッセージが生成されます。
デッドレターキューに登録しないで送信側に元のメッセージを返す必要がある場合,送信側はMQRO_DISCARD_MSGをMQRO_EXCEPTION_WITH_FULL_DATAと同時に指定する必要があります。
TP1/Message Queueは,送信側からMQRO_DISCARD_MSGオプション付きの問い合わせメッセージを受信しても,MQRO_DEAD_LETTER_Qオプションの動作をします。両方指定しない場合,MQRO_DEAD_LETTER_Qオプションの動作をします。
デフォルトオプション:
次のオプションは,ほかに報告オプションを指定しない場合に指定できます。
- MQRO_NONE
-
報告を要求しません。
MQRO_NONEは,ほかのオプションが指定されていないことを示すのに使用できます。なお,MQRO_NONEはプログラムの文書管理のために定義されています。ほかのオプションと一緒に指定しないでください。MQRO_NONEの値は0なので,これ以外の用途では使用できません。
- Reportフィールド全般について:
-
-
指定した種類の報告だけが生成されることに注意してください。例えば,到着確認報告は必要であるが例外報告は必要ない場合,メッセージがあて先キューに格納されると到着確認報告が生成されます。しかし,メッセージが到着したときにあて先キューが満杯であっても,例外報告は生成されません。報告オプションを一つも指定しなかった場合,キューマネジャによってもMCAによっても,報告は生成されません。
報告オプションの中には,ローカルキューマネジャが認識していなくても指定できるものがあります。それは,そのオプションがあて先のキューマネジャで処理される場合です。詳細は,「付録D 報告オプションとメッセージフラグ」を参照してください。
報告メッセージを要求する場合,報告先のキュー名をReplyToQフィールドに指定する必要があります。
-
障害などで応答キューへ通知できない場合,報告メッセージはデッドレターキューへ転送されます。この転送も失敗した場合,またはデッドレターキューがなかった場合は,報告メッセージのタイプによって次のようになります。
・報告メッセージが例外報告の場合,例外報告を生成させたメッセージは転送キューに残っています。その場合,メッセージが消失しないことが保証されます。
・そのほかのタイプの報告メッセージは破棄され,通常どおりに処理が続行されます。これは,到着確認報告メッセージまたは配布確認報告メッセージがすでに配布されたことを示しています。または,保持時間終了報告は関係なくなったことを示しています。
報告メッセージがいったんキュー(通常は転送キュー)に格納されると,ほかの種類のメッセージと同様に扱われます。このため,登録元メッセージが永続メッセージだった場合,報告は永続メッセージとなり破棄されることはありません。
-
報告が生成されるとき,登録元メッセージのUserIdentifierのユーザ識別子でReplyToQのキューが登録用にオープンされます。ただし,次の場合は除きます。
・MCAが例外報告を生成するとき,登録元メッセージが登録されたときのユーザ識別子が使用されます。
・キューマネジャが到着確認報告を生成するとき,登録元メッセージが登録されたときのユーザ識別子が使用されます。
報告を生成するアプリケーションは,通常,応答を生成するときと同様のユーザ識別子を使用します。つまり,登録元メッセージのユーザ識別子を使用します。
報告先がリモートキューの場合,ほかのメッセージのときと同様に,報告が必要かどうかを送信側と受信側で選択できます。
-
報告をデータ付きで要求している場合,次のようになります。
・報告データは,後部を切り捨てられることはありません。応答キューに対して報告メッセージが長過ぎた場合,デッドレターキューへ転送されます。デッドレターキューに対しても長過ぎた場合,報告メッセージは破棄されます。
・登録元データのFormatフィールドがMQFMT_XMIT_Q_HEADERの場合,報告メッセージの100バイトのデータには,MQXQH構造体は含まれません。登録元メッセージのMQXQH構造体の後ろからの部分が,報告メッセージのデータになります。転送キューの場合も転送キュー以外の場合も同様です。
-
到着確認報告,配布確認報告,または保持時間終了報告を応答キューに受信すると,登録元メッセージが到着したこと,配布されたこと,または保持時間が終了したことが保証されます。報告を要求しても,それらを受信しなかった場合,要因として次の現象が考えられます。
a. 接続が切断されたため,報告が止まっています。
b. 仲介する転送キューまたは応答キューに,満杯,登録禁止などのブロック状態があるため,報告が止まっています。
c. 報告がデッドレターキューに転送されました。
d. キューマネジャが報告を生成しようとしたときに,対応するキューにも,デッドレターキューにも登録できなかったため,報告を生成できませんでした。
e. メッセージの該当する到着,配布,または保持時間終了の状態から報告を生成するまでに,キューマネジャの障害が発生しました。ただし,次の配布確認報告のときは例外です。トランザクション内から登録元メッセージを取り出した場合,同じトランザクションの処理として配布確認報告が生成されるので,該当しません。
例外報告が届かなかった場合,上記のa.,b.,c.の場合が該当します。MCAが要求された例外報告を生成できなかった場合,つまり,応答キューとデッドレターキューのどちらにも登録できなかった場合は,登録元メッセージは送信側の転送キューに残り,回線はクローズされます。これは,例外報告が送信側で生成された場合も,回線の受信側で生成された場合も同様です。
-
登録元メッセージが一時的にブロックされた場合は,例外報告が生成され,登録元メッセージはデッドレターキューへ転送されます。ブロック状態が解消されたあとに,アプリケーションがデッドレターキューから登録元メッセージを取り出し,再びあて先キューに登録したとします。この場合,次のように処理されます。
・例外報告が生成されても,実際にはメッセージがあて先キューに到着します。
・メッセージが別のブロックにぶつかると,一つの登録元メッセージに対して複数の例外報告が生成されます。
-
- セグメント分割ができるメッセージへの報告メッセージ:
-
-
セグメントの分割ができるメッセージに,報告メッセージを要求できます。詳細は,「MsgFlagsフィールド」のMQMF_SEGMENTATION_ALLOWEDフラグの説明を参照してください。キューマネジャがメッセージのセグメント分割が必要であると判断した場合,適切な条件に合致する各セグメントに対して,報告メッセージが生成されます。したがって,アプリケーションは,要求した報告メッセージのそれぞれのタイプについて,複数の報告メッセージを受信できるようにしなければなりません。報告メッセージのGroupIdフィールドは,元のメッセージのグループ識別子となるので,複数の報告を関連づけできます。Feedbackフィールドは,それぞれの報告メッセージのタイプを識別するのに使用できます。
-
セグメントの報告メッセージを取り出す場合に,MQGMO_LOGICAL_ORDERを使用するとき,異なるタイプの報告がMQGET命令で返却されることに注意してください。例えば,COAとCODの両方の報告が,キューマネジャによってセグメント分割されたメッセージに要求されていた場合,報告メッセージに対するMQGET命令では,COAとCODの報告が不定の形式で挿入されることがあります。これは,MQGMO_COMPLETE_MSGオプションを使用すると避けられます。このとき,任意でMQGMO_ACCEPT_TRUNCATED_MSGオプションも使用できます。
MQGMO_COMPLETE_MSGを指定すると,キューマネジャは同じタイプの報告メッセージを組み立てます。例えば,最初のMQGET命令では元のメッセージに関連するすべてのCOAメッセージを組み立て,2番目のMQGET命令ではすべてのCODメッセージを組み立てることができます。なお,キューで最初に現れる報告メッセージが,最初に組み立てられます。
-
自分自身でセグメントを登録するアプリケーションは,各セグメントに異なる報告オプションを指定できます。ただし,次の点に注意してください。
・セグメントがMQGMO_COMPLETE_MSGオプションで取り出されると,先頭のセグメントの報告オプションだけが,キューマネジャに認識されます。
・セグメントが一つ一つ取り出され,そのすべてにCOD報告オプションが設定されていない場合,1回のMQGET命令で報告メッセージを取り出すためにMQGMO_COMPLETE_MSGオプションを使用したり,全報告メッセージが到着したのを確認するためにMQGMO_ALL_SEGMENTS_AVAILABLEオプションを使用したりすることはできません。
-
TP1/Message Queueのネットワークでは,キューマネジャはさまざまな機能を持っています。セグメント分割をサポートしていないキューマネジャやMCAによってセグメントに対する報告メッセージが生成されると,そのキューマネジャやMCAは報告メッセージに必要なセグメント情報を提供しないので,生成される報告メッセージの元となるメッセージを識別することが困難となります。これは,MQRO_*_WITH_DATAまたはMQRO_*_WITH_FULL_DATAオプションを指定し,報告メッセージにデータを要求することで解決できます。ただし,MQRO_*_WITH_DATAを指定すると,セグメント分割をサポートしていないキューマネジャまたはMCAによって,報告メッセージが生成されます。その場合,100バイト以下のアプリケーションデータが,報告メッセージを取り出すアプリケーションに返されることに注意してください。
-
- 報告メッセージのメッセージ記述子:
-
報告メッセージを取り出したとき,メッセージ記述子のFeedbackフィールドで報告の種類を判断できます。
キューマネジャまたはMCAによって報告が生成されるとき,報告メッセージのメッセージ記述子には,次の値が設定されます。
MQMD構造体のフィールド
値
StrucId
MQMD_STRUC_ID
Version
MQMD_VERSION_2
Report
MQRO_NONE
MsgType
MQMT_REPORT
Expiry
MQEI_UNLIMITED
Feedback
報告の種類に応じて
(MQFB_COA,MQFB_COD,MQFB_EXPIRATION,またはMQRC_*)
Encoding
登録元のメッセージ記述子から複写
CodedCharSetId
登録元のメッセージ記述子から複写
Format
登録元のメッセージ記述子から複写
Priority
登録元のメッセージ記述子から複写
Persistence
登録元のメッセージ記述子から複写
MsgId
登録元のメッセージ記述子の報告オプションどおり
CorrelId
登録元のメッセージ記述子の報告オプションどおり
BackoutCount
0
ReplyToQ
空白
ReplyToQMgr
空白
UserIdentifier
MQPMO_PASS_IDENTITY_CONTEXTオプションによって設定
AccountingToken
MQPMO_PASS_IDENTITY_CONTEXTオプションによって設定
ApplIdentityData
MQPMO_PASS_IDENTITY_CONTEXTオプションによって設定
PutApplType
MQAT_QMGR,またはMCAに応じた値
PutApplName
キューマネジャ名またはMCA名の先頭の28文字
PutDate
報告メッセージが送信された日付
PutTime
報告メッセージが送信された時刻
ApplOriginData
空白
GroupId
登録元のメッセージ記述子から複写
MsgSeqNumber
登録元のメッセージ記述子から複写
Offset
登録元のメッセージ記述子から複写
MsgFlags
登録元のメッセージ記述子から複写
OriginalLength
MQOL_UNDEFINEDでなければ,登録元のメッセージ記述子から複写される。それ以外の場合は,元のメッセージデータの長さが設定される。
報告を生成するアプリケーションは,ReplyToQMgrフィールドとコンテキストフィールドを除いて,同様の値を設定してください。ReplyToQMgrフィールドには空白を設定できます。また,コンテキストフィールドに設定する場合は,応答のときと同じオプションを使用します。通常,MQPMO_PASS_IDENTITY_CONTEXTオプションを使用します。
- 報告要求の有無の調査方法:
-
報告フィールドは,サブフィールドから構成されます。このため,ある報告が要求されているかどうかを調べる場合,次のどちらかの手順を踏んでください。
- ビット演算をサポートしているプログラミング言語では,次の手順を踏んでください。
-
-
a.
次の値から,調べたい報告の種類を一つ選択します。
報告タイプ
値
到着確認
MQRO_COA_WITH_FULL_DATA
配布確認
MQRO_COD_WITH_FULL_DATA
例外
MQRO_EXCEPTION_WITH_FULL_DATA
保持時間終了
MQRO_EXPIRATION_WITH_FULL_DATA
ここで選択したものを,値Aと呼びます。
-
b.
報告フィールドの値と値Aの論理積を取ります。この結果を,値Bと呼びます。
-
c.
値Bが,調べたい報告の種類の各値と等しいかどうかを比較します。
例えば,値AがMQRO_EXCEPTION_WITH_FULL_DATAのとき,登録元が指定した報告タイプを調べるために,値Bを次のそれぞれと比較します。
MQRO_NONE
MQRO_EXCEPTION
MQRO_EXCEPTION_WITH_DATA
MQRO_EXCEPTION_WITH_FULL_DATA
どんな順序で比較してもかまいません。アプリケーションで任意の順序で比較できます。
MQRO_PASS_MSG_IDオプションまたはMQRO_PASS_CORREL_IDオプションを調べるときも,同様の手段を利用できます。値Aとして該当する定数を選択して,上記のとおり処理してください。
-
- ビット演算をサポートしていないプログラミング言語では,次の手順を踏んでください。
-
-
a.
次の値から,調べたい報告の種類を一つ選択します。
報告タイプ
値
到着確認
MQRO_COA
配布確認
MQRO_COD
例外
MQRO_EXCEPTION
保持時間終了
MQRO_EXPIRATION
ここで選択したものを,値Aと呼びます。
-
b.
報告フィールドの値を,値Aで除算します。この結果を,値Bと呼びます。
-
c.
値Bを8で除算します。この結果を,値Cと呼びます。
-
d.
値Cを8で乗算し,それをBから減算します。この結果を,値Dと呼びます。
-
e.
値Dを値Aで乗算します。この結果を,値Eと呼びます。
-
f.
値Eが,調べたい報告の種類の各値と等しいかどうか比較します。
例えば,値AがMQRO_EXCEPTIONのとき,登録元が指定した報告タイプを調べるために,値Eを次のそれぞれと比較します。
MQRO_NONE
MQRO_EXCEPTION
MQRO_EXCEPTION_WITH_DATA
MQRO_EXCEPTION_WITH_FULL_DATA
どんな順序で比較してもかまいません。アプリケーションで任意の順序で比較できます。
この手段の擬似的なコード表現を,次に示します。
A = MQRO_EXCEPTION
B = Report/A
C = B/8
D = B−C*8
E = D*A
MQRO_PASS_MSG_IDオプションまたはMQRO_PASS_CORREL_IDオプションを調べるときも,同様の手段を使用できます。値Aとして該当する定数を選択して,上記のとおり処理してください。ただし,ステップcおよびdの値8は,2で置き換えてください。
-
Reportフィールドは,MQGET命令の出力用フィールド,およびMQPUT命令とMQPUT1命令の入力用フィールドです。
このフィールドの初期値はMQRO_NONEです。
● StrucId(MQCHAR4型) 構造体識別子
次の値を取ります。
- MQMD_STRUC_ID
-
メッセージ記述子の構造体識別子
C言語では,MQMD_STRUC_ID_ARRAYも定義されています。これは,MQMD_STRUC_IDと同じ値です。ただし,文字列ではなく文字の配列として定義されています。
これは入力用のフィールドです。
このフィールドの初期値はMQMD_STRUC_IDです。
● UserIdentifier(MQCHAR12型) ユーザ識別子
メッセージの識別コンテキストの一部です。メッセージコンテキストの詳細については,この章の「MQMD構造体 − メッセージ記述子」の「概要」,およびマニュアル「TP1/Message Queue プログラム作成の手引」を参照してください。
UserIdentifierフィールドは,メッセージを最初に登録したアプリケーションのユーザ識別子を指定します。オブジェクトをオープンする場合のObjDesc引数のAlternateUserIdフィールドに,この情報を使用できます。
この情報は,キューマネジャでは文字データとして扱われます。ただし,データの形式は規定されません。MQOPEN命令でMQOO_ALTERNATE_USER_AUTHORITYを指定した場合,またはMQPUT1命令でMQPMO_ALTERNATE_USER_AUTHORITYを指定した場合は,キューマネジャによってこの情報が生成されるときに,ObjDesc引数のAlternateUserIdが使用されます。省略した場合,環境に依存するユーザ識別子として,TP1/Message Queueでは「OPENTP1」が使用されます。
通常,このフィールドはキューマネジャによって生成される出力用のフィールドです。しかし,MQPUTまたはMQPUT1命令の場合,このフィールドを入出力用のフィールドにして,キューマネジャに生成させる代わりにフィールドを指定できます。
MQPUTまたはMQPUT1命令の場合にキューマネジャにUserIdentifierフィールドを生成させないときは,PutMsgOpts引数にはMQPMO_SET_IDENTITY_CONTEXTまたはMQPMO_SET_ALL_CONTEXTのどちらかを指定します。また,UserIdentifierフィールドにユーザ識別子を指定します。
MQPUT命令およびMQPUT1命令のPutMsgOpts引数でMQPMO_SET_IDENTITY_CONTEXTまたはMQPMO_SET_ALL_CONTEXTを指定した場合,入出力用フィールドとなります。このフィールドのヌル文字以降の情報は破棄されます。ヌル文字以降の文字は,キューマネジャによって空白に置き換えられます。MQPMO_SET_IDENTITY_CONTEXTもMQPMO_SET_ALL_CONTEXTも指定しなかった場合,このフィールドは入力時に無視されて出力専用フィールドとなり,このフィールドには「OPENTP1△△△△△」が設定されます。△は空白を表します。
MQPUT命令またはMQPUT1命令が成功すると,このフィールドには,転送されたメッセージのUserIdentifierが設定されます。メッセージにコンテキストがなかった場合,このフィールドは空白で埋められます。
MQGET命令では,出力用フィールドとなります。
このフィールドの長さは,MQ_USER_ID_LENGTHに定義されています。
このフィールドの初期値は,C言語ではヌル文字列です。そのほかのプログラミング言語では,12個の空白です。