MQRMH構造体　−　メッセージ参照ヘッダ

目的

MQRMH構造体はメッセージ参照ヘッダの形式を定義します。このヘッダは，キューマネジャ間で非常に大きなデータ（長大データといいます）を送信するために，メッセージ編集出口UOCとともに使用します。通常のメッセージ通信と異なり，長大データはキューに格納されません。代わりに，長大データへの参照だけがキューに格納されます。こうして，少数の極端に大きなメッセージによって，MQリソースが消費される可能性を減らします。

フォーマット名

MQFMT_REF_MSG_HEADER

文字セットおよびマシンコード

MQRMH構造体の文字データ，およびオフセットフィールドが示す先の文字列は，ローカルキューマネジャの文字セットに従います。これはキューマネジャのCodedCharSetId属性で指定します。MQRMH構造体の数値データは，計算機固有のマシンコードです。これはMQENC_NATIVEで指定します。

MQRMH構造体の文字セットおよびマシンコードは，次に示す構造体中のCodedCharSetIdおよびEncodingフィールドに設定する必要があります。

• MQMD構造体（MQRMH構造体がメッセージデータの先頭にある場合）

• MQRMH構造体に先行するヘッダ構造体（その他のすべての場合）

使用方法

アプリケーションは長大データを省略して，MQRMH構造体で構成されるメッセージを登録します。メッセージチャネルエージェント（MCA）が転送キューからメッセージを取り出すとき，ユーザが作成したメッセージ編集出口UOCが呼び出されてメッセージ参照ヘッダを処理します。出口はMQRMH構造体が示す長大データを参照メッセージに追加できます。その後，MCAはチャネルを介して次のキューマネジャにメッセージを送信します。

受信側では，参照メッセージを待つメッセージの出口が存在しなければなりません。参照メッセージを受信すると，出口はメッセージのMQRMH構造体に続くデータからオブジェクトを生成し，データなしの参照メッセージを返します。その後，参照メッセージはアプリケーションによって取り出されます。

通常，MQRMH構造体が，メッセージのすべてです。ただし，メッセージが転送キューにある場合は，一つ以上のヘッダがMQRMH構造体の前に付きます。

参照メッセージは配布リストに送信されることも可能です。この場合，メッセージが転送キューにあるときは，MQDH構造体およびMQDH構造体に関連するレコードが，MQRMH構造体の前にあります。

注意事項

参照メッセージはセグメント分割されたメッセージとして送信されてはいけません。メッセージの出口は，セグメント分割されたメッセージを正しく処理できません。

データ変換

データ変換時，MQRMH構造体では，送信元の環境データ，送信元オブジェクト名称，あて先環境変数，およびあて先オブジェクト名がデータ変換されます。構造体の先頭のStrucLength外にあるバイトは，データ変換後に廃棄されるか，未定義の値になります。長大データは，次に示すすべての条件が満たされる場合に変換されます。

• データが変換されるときに長大データがメッセージに存在する場合

• MQRMH構造体のFormatフィールドがMQFMT_NONE以外の値である場合

• ユーザの記述したデータ変換出口が，指定されたフォーマット名で存在する場合

ただし，通常，メッセージがキューに存在するとき，長大データはメッセージには存在しません。したがって，MQGMO_CONVERTオプションでは変換されないことに注意してください。

●　CodedCharSetId（MQLONG型）　文字セット識別子

長大データの文字セット識別子です。

これは，長大データの文字セット識別子を指定します。MQRMH構造体自身の文字データには適用されません。

MQPUTまたはMQPUT1命令では，アプリケーションはデータに合った値をこのフィールドに設定する必要があります。

MQCCSI_INHERIT

この構造体の文字セット識別子を引き継ぎます。

この構造体に続くデータの文字データは，この構造体と同じ文字セットです。

メッセージで送信される構造体のこの値を，キューマネジャは構造体の実際の文字セット識別子に変更します。エラーが発生しない場合，MQGET命令ではMQCCSI_INHERITは返されません。

MQMD構造体のPutApplTypeフィールドの値がMQAT_BROKERの場合，MQCCSI_INHERITは使用できません。

このフィールドの初期値はMQCCSI_UNDEFINEDです。

●　DataLogicalLength（MQLONG型）　長大データ長

DataLogicalLengthフィールドはMQRMH構造体で参照される長大データの長さを指定します。

長大データが実際にメッセージ中に存在するときは，MQRMH構造体のすぐあとに続きます。全メッセージ長から，MQRMH構造体の終端のメッセージを含むオフセットを減算すると，存在する長大データの長さが求められます。

データがメッセージ内に存在すると，DataLogicalLengthフィールドは，関連するデータ量を指定します。通常，DataLogicalLengthフィールドは，実際にメッセージに存在するデータ長と同じ値となります。

MQRMH構造体が，指定された論理オフセットからのオブジェクト内にある残りのデータを表す場合，DataLogicalLengthフィールドには0が指定できます。つまり，長大データはメッセージ内に存在しません。

データが存在しないとき，MQRMH構造体の終端がメッセージの終端と一致します。

このフィールドの初期値は0です。なお，長大データのデータ変換が正常に行われた場合，変換後の長大データ長がDataLogicalLengthフィールドに返却されます。

●　DataLogicalOffset（MQLONG型）　長大データ低位オフセット

一部が長大データによって形成されたオブジェクトの開始位置からの，長大データの低位オフセットを指定します。オブジェクトの開始位置から長大データまでのオフセットは論理オフセットといいます。これは，MQRMH構造体の先頭から長大データまでの物理的オフセットではありません。物理的なオフセットはStrucLengthフィールドで与えられます。

参照メッセージを使用して大きなオブジェクトを送信するために，論理オフセットは二つのフィールドに分割されます。実際の論理オフセットは，これら二つのフィールドの合計で与えられます。

• DataLogicalOffsetフィールドは，論理オフセットを1000000000で除算したときの余りを表します。0から999999999の範囲で値を取ります。

• DataLogicalOffset2フィールドは，論理オフセットを1000000000で除算したときの結果を表します。結果は，論理オフセットに存在する1000000000の倍数となります。倍数の数は0から999999999の範囲で値を取ります。

このフィールドの初期値は0です。

●　DataLogicalOffset2（MQLONG型）　長大データ高位オフセット

一部が長大データによって形成されたオブジェクトの開始位置からの，長大データの高位オフセットを指定します。0から999999999の範囲の値を取ります。詳細については，「DataLogicalOffsetフィールド」を参照してください。

このフィールドの初期値は0です。

●　DestEnvLength（MQLONG型）　あて先環境データ長

このフィールドが0の場合，あて先環境データは存在しません。したがって，DestEnvOffsetフィールドは無視されます。

このフィールドの初期値は0です。

●　DestEnvOffset（MQLONG型）　あて先環境データオフセット

MQRMH構造体の先頭からあて先環境データまでのオフセットを指定します。あて先環境データは，参照メッセージの作成者が知っている場合は，作成者によって指定されます。作成者があて先環境データを知らない場合は，ユーザ作成メッセージ出口が，必要な環境情報を特定しなければなりません。

あて先環境データの長さはDestEnvLengthフィールドによって与えられます。この長さが0の場合，あて先環境データは存在しません。したがってDestEnvOffsetフィールドは無視されます。存在する場合，あて先環境データは構造体の先頭からStrucLengthフィールドの間に存在しなければなりません。

アプリケーションは，あて先環境データが構造体の最後の固定フィールドのあとからすぐに開始したり，SrcEnvOffsetフィールド，SrcNameOffsetフィールド，およびDestNameOffsetフィールドで指定されるデータとあて先環境データが隣接したりすることを仮定しないでください。

このフィールドの初期値は0です。

●　DestNameLength（MQLONG型）　あて先オブジェクト名長

このフィールドが0の場合，あて先オブジェクト名はありません。したがって，DestNameOffsetフィールドは無視されます。

このフィールドの初期値は0です。

●　DestNameOffset（MQLONG型）　あて先オブジェクトのオフセット

MQRMH構造体の先頭からあて先オブジェクト名までのオフセットを指定します。あて先オブジェクト名は，参照メッセージの作成者が知っている場合は，作成者によって指定されます。作成者があて先オブジェクト名を知らない場合は，ユーザ作成メッセージ出口が作成されたり変更されたりするオブジェクトを識別します。

あて先オブジェクト名の長さは，DestNameLengthフィールドによって与えられます。この長さが0の場合は，あて先オブジェクト名は存在しません。したがって，DestNameOffsetフィールドは無視されます。存在する場合，あて先オブジェクト名は，構造体の先頭からStrucLengthフィールドの間に存在しなければなりません。

アプリケーションは，SrcEnvOffsetフィールド，SrcNameOffsetフィールド，およびDestEnvOffsetフィールドで指定されるデータとあて先オブジェクト名が隣接することを仮定しないでください。

このフィールドの初期値は0です。

●　Encoding（MQLONG型）　マシンコード形式

長大データのマシンコード形式です。

長大データのマシンコードを指定します。MQRMH構造体自身の数値データには適用されません。

MQPUTおよびMQPUT1命令では，アプリケーションはデータに合った値をこのフィールドに設定する必要があります。

このフィールドの初期値はMQENC_NATIVEです。

●　Flags（MQLONG型）　フラグ

メッセージを参照するフラグです。

次のフラグが定義されています。

MQRMHF_LAST

オブジェクトの最終部分を表します。

このフラグは，参照メッセージが参照オブジェクトの最終部分を含んでいる，または最終部分であることを示しています。

MQRMHF_NOT_LAST

オブジェクトの最終部分ではないことを表します。

MQRMHF_NOT_LASTはプログラムの文書化の目的で定義されています。値としては0が定義されていますが，プログラムを文書化する以外の目的はありません。

このフィールドの初期値はMQRMHF_NOT_LASTです。

●　Format（MQCHAR8型）　フォーマット名

長大データのフォーマット名です。

長大データのフォーマット名を指定します。

MQPUTおよびMQPUT1命令では，アプリケーションはデータに合った値をこのフィールドに設定する必要があります。このフィールドの設定規則はMQMD構造体のFormatフィールドと同じです。

このフィールドの初期値は，MQFMT_NONEです。

●　ObjectInstanceId（MQBYTE24型）　オブジェクトインスタンス識別子

オブジェクトの特別なインスタンスを識別するために使用します。使用しない場合は，次の値を設定してください。

MQOII_NONE

オブジェクトインスタンス識別子は指定されません

この値はフィールドの長さと同じ2進数の0です。

C言語では，MQOII_NONE_ARRAYも定義されています。これは，MQOII_NONEと同じ値です。ただし，文字列ではなく文字の配列として定義されています。

このフィールドの長さは，MQ_OBJECT_INSTANCE_ID_LENGTHに定義されています。

このフィールドの初期値はMQOII_NONEです。

●　ObjectType（MQCHAR8型）　オブジェクトタイプ

メッセージ出口でサポートする参照メッセージのタイプを識別するために使用できる名称です。この名称を指定する場合，次に示す文字を使用することをお勧めします。

• 英大文字のA〜Z

• 数値の0〜9

このフィールドの初期値は8個の空白です。

●　SrcEnvLength（MQLONG型）　送信元環境データ長

このフィールドが0の場合，送信元メッセージの環境データは存在しません。したがって，SrcEnvOffsetフィールドは無視されます。

このフィールドの初期値は0です。

●　SrcEnvOffset（MQLONG型）　送信元環境データオフセット

MQRMH構造体の先頭から送信元環境データまでのオフセットを指定します。送信元環境データは，参照メッセージの作成者が知っている場合は，作成者によって指定されます。作成者が送信元環境データを知らない場合は，ユーザ作成メッセージ出口が必要な環境情報を特定しなければなりません。

送信元環境データの長さは，SrcEnvLengthフィールドによって与えられます。この長さが0の場合，送信元環境データは存在しません。したがって，SrcEnvOffsetフィールドは無視されます。送信元環境データが存在する場合，構造体の先頭からStrucLengthフィールドの間に存在しなければなりません。

アプリケーションは，送信元環境データが構造体の最後の固定フィールドのあとからすぐに開始したり，SrcNameOffsetフィールド，DestEnvOffsetフィールド，およびDestNameOffsetフィールドで指定されるデータと送信元環境データが隣接したりすることを仮定しないでください。

このフィールドの初期値は0です。

●　SrcNameLength（MQLONG型）　送信元オブジェクト名長

このフィールドが0の場合，送信元オブジェクト名はありません。したがって，SrcNameOffsetフィールドは無視されます。

このフィールドの初期値は0です。

●　SrcNameOffset（MQLONG型）　送信元オブジェクトのオフセット

MQRMH構造体の先頭から送信元オブジェクト名までのオフセットを指定します。送信元オブジェクト名は，参照メッセージの作成者が知っている場合は，作成者によって指定されます。作成者が送信元オブジェクト名を知らない場合は，ユーザ作成メッセージ出口がアクセスするオブジェクトを識別しなければなりません。

送信元オブジェクト名の長さはSrcNameLengthフィールドによって与えられます。この長さが0の場合，送信元オブジェクト名は存在しません。したがって，SrcNameOffsetフィールドは無視されます。存在する場合，送信元オブジェクト名は構造体の先頭からStrucLengthフィールドの間に存在しなければなりません。

アプリケーションは，SrcEnvOffsetフィールド，DestEnvOffsetフィールド，およびDestNameOffsetフィールドで指定されるデータと送信元オブジェクト名が隣接することを仮定しないでください。

このフィールドの初期値は0です。

●　StrucId（MQCHAR4型）　構造体識別子

次の値を取ります。

MQRMH_STRUC_ID

参照メッセージヘッダ構造体の識別子

C言語では，MQRMH_STRUC_ID_ARRAYも定義されています。これは，MQRMH_STRUC_IDと同じ値です。ただし文字列ではなく文字の配列として定義されています。

このフィールドの初期値はMQRMH_STRUC_IDです。

●　StrucLength（MQLONG型）　構造体長

MQRMH構造体の構造体長を表します。固定フィールドの終端の文字列を含みます。ただし，長大データは含んでいません。

このフィールドの初期値は0です。

●　Version（MQLONG型）　構造体バージョン番号

次の値を取ります。

MQRMH_VERSION_1

バージョン1の参照メッセージヘッダの構造体バージョン番号

次の値には，現在のバージョンのバージョン番号を指定します。

MQRMH_CURRENT_VERSION

現在のバージョンの参照メッセージヘッダの構造体バージョン番号

このフィールドの初期値はMQRMH_VERSION_1です。