MQPMO構造体　−　メッセージ登録オプション

目的

MQPMO構造体によって，アプリケーションはメッセージのキューへの格納方法を制御できます。この構造体は，MQPUTおよびMQPUT1命令の入出力用の引数です。

バージョン

MQPMO構造体のバージョンには1および2があります。しかし，すべての環境でMQPMO_VERSION_2がサポートされているわけではありません。複数の環境にアプリケーションを移植する場合は，使用するバージョンのMQPMO構造体が，すべての環境でサポートされている必要があります。MQPMO_VERSION_2以降の構造体にだけ存在するフィールドについては，そのことをフィールドの説明に記載しています。

サポートするプログラミング言語のCOPYファイルとINCLUDEファイルでは，最新バージョンのMQPMO構造体が提供されます。しかし，Versionフィールドの初期値はMQPMO_VERSION_1です。バージョン1の構造体にないフィールドを使用する場合は，アプリケーションで使用したいバージョンの番号をVersionフィールドに設定してください。

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

MQPMO構造体のデータは，ローカルキューマネジャの文字セットおよびマシンコードに従います。それぞれ，キューマネジャのCodedCharSetId属性およびMQENC_NATIVEで指定します。TP1/Message Queue Accessのクライアントアプリケーションの場合，MQPMO構造体はクライアントの文字セットとマシンコードに従います。

●　Context（MQHOBJ型）　コンテキスト

入力キューのオブジェクトハンドルです。

MQPMO_PASS_IDENTITY_CONTEXTまたはMQPMO_PASS_ALL_CONTEXTを指定した場合，このフィールドに入力キューハンドルを指定します。登録するメッセージのコンテキスト情報は，そのキューハンドルから取得されます。

MQPMO_PASS_IDENTITY_CONTEXTもMQPMO_PASS_ALL_CONTEXTも指定しなかった場合，このフィールドは無視されます。

これは入力用のフィールドです。

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

●　InvalidDestCount（MQLONG型）　送信に失敗したキューの数

配布リスト中のキューの中で，送信できなかったメッセージの数です。オープンは成功したが登録に失敗したキューや，オープンに失敗したキューの数も含まれます。このフィールドは配布リストではない単一のキューへの登録時にも設定されます。

注意事項

このフィールドは，MQPUT命令またはMQPUT1命令のCompCode引数がMQCC_OKまたはMQCC_WARNINGの場合だけ設定されます。CompCode引数がMQCC_FAILEDの場合は設定されません。

これは出力用のフィールドです。

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

なお，このフィールドは，VersionフィールドがMQPMO_VERSION_2より前の場合は設定されません。

●　KnownDestCount（MQLONG型）　ローカルキューの数

配布リストの中で，MQPUT命令またはMQPUT1命令による，ローカルキューであるキューへの送信が成功したキューの数を示しています。ローカルな転送キューが最初のメッセージ登録に使用された場合も，値はリモートキューで受信されるキューは含みません。このフィールドは配布リストではない単一のキューへの登録時にも設定されます。

これは出力用のフィールドです。

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

なお，このフィールドは，VersionフィールドがMQPMO_VERSION_2より前の場合は設定されません。

●　Options（MQLONG型）　登録オプション

MQPUT命令およびMQPUT1命令の動作を制御します。

指定できるオプションを説明します。なお，指定しなくてもかまいません。二つ以上の値を指定する場合は，次のどちらかに従ってください。

• それぞれを加算します。ただし，同じ値は2回以上加算しないでください。

• プログラミング言語がビット演算をサポートしている場合に，それぞれのビット論理和を取ります。

同時に指定できない組み合わせは，そのつど示します。それ以外の組み合わせは自由です。オプションおよびその指定方法の一覧については，「付録A　命令および引数の一覧」を参照してください。

同期点オプション：

MQPUTまたはMQPUT1命令のトランザクションへの参加に関連するオプションを次に示します。

MQPMO_SYNCPOINT

同期点でメッセージを登録します。

通常のトランザクションの範囲内で登録します。トランザクションがコミットするまでは，トランザクション内から登録したメッセージは有効になりません。トランザクションがロールバックすると，メッセージは取り消されます。

このオプションは，ローカルキューマネジャが同期点処理をサポートしているときだけ指定できます。同期点処理をサポートしていないキューマネジャでMQPMO_SYNCPOINTを指定した場合，完了コードMQCC_FAILED，理由コードMQRC_SYNCPOINT_NOT_AVAILABLEで命令は終了します。同期点の取得とトランザクションについては，マニュアル「TP1/Message Queue プログラム作成の手引」を参照してください。

このオプションとMQPMO_NO_SYNCPOINTオプションのどちらも指定しなかった場合，登録命令がトランザクション内に含められるかどうかは，環境に依存します。TP1/Message Queueでは，この命令をトランザクション内から呼び出したかどうかで，省略時にトランザクション内に含められるかどうかが決まります。省略時の動作が環境によって異なるため，移植を考慮するアプリケーションでは，オプションを省略しないでください。つまり，MQPMO_SYNCPOINTオプションかMQPMO_NO_SYNCPOINTオプションを，明確に指定してください。

MQPMO_NO_SYNCPOINTオプションと同時にMQPMO_SYNCPOINTオプションを指定できません。

MQPMO_NO_SYNCPOINT

同期点の処理なしでメッセージを登録します。

通常のトランザクションの範囲外で登録します。メッセージは登録直後から有効になります。トランザクションがロールバックしても，メッセージは取り消されません。

このオプションとMQPMO_SYNCPOINTオプションのどちらも指定しなかった場合，登録命令がトランザクション内に含められるかどうかは，環境に依存します。TP1/Message Queueでは，この命令をトランザクション内から呼び出したかどうかで，省略時にトランザクション内に含められるかどうかが決まります。省略時の動作が環境によって異なるため，移植を考慮するアプリケーションでは，オプションを省略しないでください。つまり，MQPMO_SYNCPOINTオプションかMQPMO_NO_SYNCPOINTオプションのどちらかを，明確に指定してください。

MQPMO_NO_SYNCPOINTオプションと同時にMQPMO_SYNCPOINTオプションを指定できません。

同期点のオプションとキューマネジャのSyncPoint属性の関係を，次の表に示します。

キューマネジャの SyncPoint属性	MQPUT/MQPUT1 命令の呼び出し位置	MQPUT/MQPUT1命令の 同期点のオプション
		MQPMO_ SYNCPOINT	MQPMO_ NO_SYNCPOINT	省略
MQSP_AVAILABLE	トランザクション内	1	2	1
	トランザクション外	×	2	2
MQSP_NOT_AVAILABLE	トランザクション内	×	2	×
	トランザクション外	×	2	2

（凡例）

1：命令はトランザクション内に含まれます。

2：命令はトランザクション内に含まれません。

×：命令は理由コードMQRC_SYNCPOINT_NOT_AVAILABLEで失敗します。

メッセージ識別子および相関識別子オプション：

キューマネジャに新しいメッセージ識別子または相関識別子を生成させるオプションを次に示します。

MQPMO_NEW_MSG_ID

新しいメッセージ識別子を生成します。

MQMD構造体のMsgIdフィールドの内容を新しいメッセージ識別子に置き換えるように，キューマネジャに指定します。メッセージ識別子はメッセージとともに送信され，MQPUT命令またはMQPUT1命令の出力でアプリケーションに返されます。

このオプションは，メッセージが配布リストに登録されるときにも指定できます。この章の「MQPMR構造体　−　登録メッセージレコード」のMsgIdフィールド参照してください。

MQPMO_NEW_MSG_IDを指定すると，アプリケーションはMQPUT命令またはMQPUT1命令に先立って，MsgIdフィールドをMQMI_NONEにリセットする必要がなくなります。

MQPMO_NEW_CORREL_ID

新しい相関識別子を生成します。

キューマネジャにMQMD構造体のCorrelIdフィールドの内容を，新しい相関識別子に置き換えるよう指定できます。相関識別子はメッセージとともに送信され，MQPUT命令またはMQPUT1命令の出力でアプリケーションに返されます。

このオプションは，メッセージが配布リストに登録されるときにも指定できます。この章の「MQPMR構造体　−　登録メッセージレコード」でCorrelIdフィールドを参照してください。

MQPMO_NEW_CORREL_IDオプションは，アプリケーションがユニークな相関識別子を必要とする場合に有効です。

グループとセグメントに関するオプション：

グループ内のメッセージおよび論理メッセージのセグメントの処理に関連するオプションを次に示します。オプションを理解するために，次の用語について説明します。

物理メッセージ

キューに登録したり取り出したりすることのできる最も小さい情報単位です。通常，単一のMQPUT命令，MQPUT1命令またはMQGET命令で指定したり取り出したりする情報に該当します。

それぞれの物理メッセージはメッセージ記述子（MQMD構造体）を持っています。

キューマネジャによって定義されているわけではありませんが，一般的に，物理メッセージはメッセージ記述子（MQMD構造体のMsgIdフィールド）の値で区別されます。

論理メッセージ

アプリケーション情報の一単位です。システムの強制がない場合，論理メッセージは物理メッセージと同じである場合があります。ただし，論理メッセージが極端に大きい場合，論理メッセージを二つまたはそれ以上のセグメントと呼ばれる物理メッセージに分割することをお勧めします。また，分割が必要となる場合もあります。

セグメント分割された論理メッセージは，同一のヌルではないグループ記述子（MQMD構造体のGroupIdフィールド）と同一のメッセージシーケンス番号（MQMD構造体のMsgSeqNumberフィールド）を持つ二つ以上の物理メッセージによって構成されます。セグメントはセグメントオフセット（MQMD構造体のOffsetフィールド）の値で区別されます。セグメントオフセットは，論理メッセージのデータ先頭からの，物理メッセージのデータの位置を表します。それぞれのセグメントは物理メッセージであるため，論理メッセージのセグメントは，通常異なるメッセージ記述子を持ちます。

セグメント分割はされていないメッセージのうち，送信アプリケーションによってセグメント分割が許可されている論理メッセージも，ヌルではないグループ記述子を持ちます。この場合，論理メッセージがメッセージグループに属していないときは，そのグループ記述子を持つ物理メッセージはただ一つしか存在しないことになります。送信アプリケーションによってセグメント分割が禁止されている論理メッセージがメッセージグループに属していない場合は，ヌルのグループ記述子（MQGI_NONE）を持っています。

メッセージグループ

ヌルではない同一のグループ記述子を持つ一つ以上の物理メッセージの集まりです。

グループ内の論理メッセージは，メッセージシーケンス番号の値で区別されます。メッセージシーケンス番号は，1〜Nの整数範囲となります。なお，Nはグループ内の論理メッセージの数を表します。一つ以上の論理メッセージがセグメント分割されている場合，グループ内にはN個以上の物理メッセージが存在します。

次に，メッセージが，MQGET命令で返却される方法を制御する個々のオプションについて説明します。

MQPMO_LOGICAL_ORDER

グループ内のメッセージと論理メッセージのセグメントを論理的な順序で登録します。

このオプションを指定すると，アプリケーションがキューマネジャにグループ内のメッセージと論理メッセージのセグメントの登録方法を通知します。MQPUT命令でだけ指定できます。MQPUT1命令で指定すると不正となります。

MQPMO_LOGICAL_ORDERが指定されると，アプリケーションはMQPUT命令を次のように発行します。

• 各論理メッセージのセグメントを，セグメントオフセットが0から空きがなくなるまで，昇順で登録します。

• 論理メッセージの全セグメントを，次の論理メッセージのセグメント登録の前に登録します。

• 各メッセージグループの論理メッセージを，メッセージシーケンス番号が1から空きがなくなるまで，昇順で登録します。

• メッセージグループの全論理メッセージを次のメッセージグループの論理メッセージ登録の前に登録します。

上記の順序を論理的順序といいます。

アプリケーションは，キューマネジャにグループ内のメッセージと論理メッセージのセグメントの登録方法を通知しているため，おのおののMQPUT命令でグループとセグメントの情報を保持したり，更新したりする必要がありません。特に，MQMD構造体のGroupIdフィールド，MsgSeqNumberフィールド，およびOffsetフィールドは，キューマネジャが適当な値に設定するため，アプリケーションは設定する必要がありません。アプリケーションは，次に示す内容を指示するため，MQMD構造体のMsgFlagsフィールドだけ指定する必要があります。

• メッセージがグループに属する，または論理メッセージのセグメントであることを指示する

• グループ内の最終メッセージ，または論理メッセージの最終セグメントを指示する

メッセージグループまたは論理メッセージが開始すると，次のMQPUT命令はMQMD構造体のMsgFlagsフィールドに適当なMQMF_*フラグを指定する必要があります。アプリケーションが，メッセージグループが終了していないときにグループに属さないメッセージを登録しようとしたり，論理メッセージが終了していないときにセグメントではないメッセージを登録しようとしたりした場合，命令はMQRC_INCOMPLETE_GROUPまたはMQRC_INCOMPLETE_MSGの理由コードで失敗します。

ただし，キューマネジャは，現在のメッセージグループおよび現在の論理メッセージに関する情報を保持しています。アプリケーションはMQMF_LAST_MSG_IN_GROUPまたはMQMF_LAST_SEGMENTを指定してメッセージを送信することで，MQPUT命令を再発行する前にグループに属していない，かつセグメントでもないメッセージを登録するために保持されている情報を終了できます。ただし，この場合アプリケーションが送信するメッセージには，メッセージデータがないときもあります。

オプションとフラグの正しい組み合わせ，およびキューマネジャが使用するGroupIdフィールド，MsgSeqNumberフィールド，およびOffsetフィールドの値を次の表に示します。表に示されていないオプションとフラグの組み合わせは誤りです。

指定するオプション				命令に先行するグループと論理メッセージの状態		キューマネジャが使用する値
MQPMO_ LOG ICAL_ ORDER	MQMF_ MSG_ IN_ GROUP またはMQMF_ LAST_ MSG_ IN_ GROUP	MQMF_ SEG MENT または MQMF_ LAST_ SEG MENT	MQMF_ SEG MENT ATION_ ALLO WED	命令に先行する現在のメッセージグループがある	命令に先行する現在の論理メッセージがある	Group Id	MsgSeq Number	Offset
○	×	×	×	×	×	MQGI_ NONE	1	0
○	×	×	○	×	×	新グループ識別子	1	0
○	×	○	−	×	×	新グループ識別子	1	0
○	×	○	−	×	○	前グループ識別子	1	前オフセット値と前セグメント長の和
○	○	−	−	×	×	新グループ識別子	1	0
○	○	−	−	○	×	前グループ識別子	前シーケンス番号に1を加算	0
○	○	○	−	○	○	前グループ識別子	前シーケンス番号	前オフセット値と前セグメント長の和
×	×	×	×	−	−	MQGI_ NONE	1	0
×	×	×	○	−	−	MQGI_ NONEの場合：新グループ識別子 それ以外の場合：フィールドの値	1	0
×	×	○	−	−	−	MQGI_ NONEの場合：新グループ識別子 それ以外の場合：フィールドの値	1	フィールドの値
×	○	×	−	−	−	MQGI_ NONEの場合：新グループ識別子 それ以外の場合：フィールドの値	フィールドの値	0
×	○	○	−	−	−	MQGI_ NONEの場合：新グループ識別子 それ以外の場合：フィールドの値	フィールドの値	フィールドの値

（凡例）

○：該当します。

×：該当しません。

−：有無に関係ありません。

注意事項

MQPMO_LOGICAL_ORDERは，MQPUT1命令に対しては無効です。

MsgIdフィールドに対して，MQPMO_NEW_MSG_IDまたはMQMI_NONEが指定されたとき，キューマネジャは新しいメッセージ識別子を生成します。その場合は，ほかのフィールドの値を使用します。

CorrelIdフィールドに対してMQPMO_NEW_CORREL_IDが指定されたとき，キューマネジャは新しい相関識別子を生成します。その場合は，ほかのフィールドの値を使用します。

MQPMO_LOGICAL_ORDERが指定されたとき，グループ内の全メッセージと論理メッセージの全セグメントのMQMD構造体のPersistenceフィールドに，同一の値を指定してキューマネジャに登録しなければなりません。つまり，すべてが永続的であるか，または非永続であるかのどちらかでなければなりません。この条件が満たされない場合，MQPUT命令は理由コードMQRC_INCONSISTENT_PERSISTENCEで失敗します。

MQPMO_LOGICAL_ORDERオプションが同期点に及ぼす影響を次に示します。

• グループの最初の論理メッセージまたはセグメントがトランザクション内で登録された場合，同じキューハンドルを使うときは，グループ内にあるほかのすべての論理メッセージとセグメントはトランザクション内で登録されなければなりません。ただし，メッセージが同じトランザクション内で登録される必要はありません。したがって，多くの物理メッセージで構成されるメッセージグループは，キューハンドルで二つ以上の連続したトランザクションに分割することが可能になります。

• グループの最初の論理メッセージ，またはセグメントがトランザクション内で登録されなかった場合，同じキューハンドルを使うときは，グループ内のほかの論理メッセージとセグメントを同じトランザクション内で登録することはできません。

上記の条件を満たさなかった場合，MQPUT命令はMQRC_INCONSISTENT_UOWの理由コードで失敗します。

MQPMO_LOGICAL_ORDERが指定されたとき，MQPUT命令で指定されたMQMD構造体はMQMD_VERSION_2より前のバージョンではいけません。この条件が満足されない場合は，MQRC_WRONG_MD_VERSIONの理由コードで失敗します。

MQPUT命令にMQPMO_LOGICAL_ORDERを指定しない場合，グループのメッセージおよび論理メッセージのセグメントは，どのような順序で登録してもかまいません。また，完全なメッセージグループや完全な論理メッセージを登録する必要もありません。GroupIdフィールド，MsgSeqNumberフィールド，Offsetフィールド，およびMsgFlagsフィールドには，アプリケーションによって正しい値が設定されます。

システムに障害が起きた場合，メッセージグループや論理メッセージを途中から再開する方法を示します。システム再開時，アプリケーションはGroupIdフィールド，MsgSeqNumberフィールド，Offsetフィールド，MsgFlagsフィールド，およびPersistenceフィールドに適当な値を設定します。その後，MQPMO_SYNCPOINTまたはMQPMO_NO_SYNCPOINTに適当な値を設定します。すると，MQPMO_LOGICAL_ORDERを指定しないでMQPUT命令を発行できます。このMQPUT命令が成功したとき，キューマネジャは，グループとセグメントの情報を保持します。そのキューハンドルを使用した後続のMQPUT命令では，通常のMQPMO_LOGICAL_ORDERを指定できます。

キューマネジャがMQPUT命令用に保持しているグループ情報およびセグメント情報は，MQGET命令用に保持しているグループ情報およびセグメント情報とは別です。

どのキューハンドルについても，アプリケーションではMQPMO_LOGICAL_ORDERを指定したMQPUT命令と指定しないMQPUT命令を混在してもかまいませんが，次の点に注意してください。

• MQPMO_LOGICAL_ORDERを指定していない場合，MQPUT命令が成功するたびに，キューマネジャはアプリケーションに指定された値を，キューハンドルのグループおよびセグメント情報に設定します。その情報で，キューハンドルに対してキューマネジャが保持していたグループとセグメントの情報を置き換えます。

• MQPMO_LOGICAL_ORDERが指定されない場合，現在のメッセージグループまたは論理メッセージが存在するとき，その命令は失敗しません。命令はMQCC_WARNING完了コードで成功します。MQPUT命令とMQCLOSE命令が，グループ情報およびセグメント情報で矛盾している場合の結果を次の表に示します。

  実行時の命令	直前の命令がMQPMO_LOGICAL_ORDER指定ありのMQPUT命令	直前の命令がMQPMO_LOGICAL_ORDER指定なしのMQPUT命令
  MQPMO_LOGICAL_ORDER指定ありのMQPUT命令	MQCC_FAILED	MQCC_FAILED
  MQPMO_LOGICAL_ORDER指定なしのMQPUT命令	MQCC_WARNING	MQCC_OK
  非永続グループと論理メッセージありのMQCLOSE命令	MQCC_WARNING	MQCC_OK

  上記の場合で完了コードがMQCC_OKではないときは，理由コードは次のどれかになります。

  　MQRC_INCOMPLETE_GROUP

  　MQRC_INCOMPLETE_MSG

  　MQRC_INCONSISTENT_PERSISTENCE

  　MQRC_INCONSISTENT_UOW

  注意事項

  キューマネジャは，MQPUT1命令でグループとセグメントの情報をチェックしません。

論理的な順序でメッセージとセグメントを単純に登録したいアプリケーションでは，MQPMO_LOGICAL_ORDERを指定することをお勧めします。このオプションによってキューマネジャがグループとセグメントの情報を管理することを指定できるため，アプリケーションはそれらの情報を管理する必要はありません。しかし，アプリケーションによっては，MQPMO_LOGICAL_ORDERオプションが提供する機能より高い制御機能を必要とする場合があります。その場合，このオプションを指定しないでください。MQPMO_LOGICAL_ORDERを指定しなかったとき，アプリケーションは，MQPUT命令またはMQPUT1命令に先立って，MQMD構造体のGroupIdフィールド，MsgSeqNumberフィールド，Offsetフィールド，およびMsgFlagsフィールドを正しく設定しなければなりません。

例えば，受信した物理メッセージをグループまたは論理メッセージのセグメントに属するかどうか関係なく転送するアプリケーションには，次に示す理由のため，MQPMO_LOGICAL_ORDERを指定しないでください。

• メッセージが順番に取り出されたり登録されたりする場合，MQPMO_LOGICAL_ORDERを指定すると，新しいグループ識別子がメッセージに割り当てられます。その結果，メッセージの生成元がメッセージグループの結果の応答や報告メッセージを関連づけることが困難になります。

• 送信側と受信側のキューマネジャ間に複数の通信路がある複雑なネットワークの場合，物理メッセージは順序どおりに到着しません。MQPMO_LOGICAL_ORDERおよびMQGET命令で対応するMQGMO_LOGICAL_ORDERを指定しないことで，転送するアプリケーションは各メッセージが到着すると，次の論理的な順序のメッセージを待たないで，そのメッセージを取り出したり転送したりできます。

グループのメッセージや，論理メッセージのセグメントに対する報告メッセージを生成するアプリケーションにも，MQPMO_LOGICAL_ORDERを指定しないでください。

MQPMO_LOGICAL_ORDERは，ほかのMQPMO_*オプションのどれとも同時に指定できます。

コンテキストオプション：

メッセージコンテキストの処理を制御するオプションを次に示します。

MQPMO_NO_CONTEXT

メッセージコンテキストを使用しません。

識別コンテキストも登録元コンテキストも使用しません。文字フィールドは空白，バイトフィールドはヌル，数値フィールドは0となります。

MQPMO_DEFAULT_CONTEXT

省略時のメッセージコンテキストを使用します。

識別コンテキストも登録元コンテキストも，省略時の仮定値を使用します。キューマネジャは，メッセージ記述子のコンテキストフィールドを次のように設定します。

MQMD構造体のフィールド	値
UserIdentifier	"OPENTP1"またはAlternateUserId（環境に依存する値）
AccountingToken	MQACT_NONE（環境に依存する値）
ApplIdentityData	空白
PutApplType	MQAT_OPEN_TP1（環境に依存する値）
PutApplName	ユーザサーバ名（SUP名，SPP名）（環境に依存する値）
PutDate	メッセージを登録した日付
PutTime	メッセージを登録した時刻
ApplOriginData	空白

メッセージコンテキストおよびコンテキスト情報の制御については，マニュアル「TP1/Message Queue プログラム作成の手引」を参照してください。

このほかのコンテキストオプションを指定しなかった場合，このオプションが仮定されます。

MQPMO_PASS_IDENTITY_CONTEXT

入力キューハンドルの識別コンテキストを引き渡します。

関連するコンテキスト情報をメッセージに使用します。識別コンテキストとして，Contextフィールドに指定したキューハンドルの情報を使用します。登録元コンテキストは，キューマネジャによって，MQPMO_DEFAULT_CONTEXTと同様の方法で設定されます。メッセージコンテキストおよびコンテキスト情報の制御については，マニュアル「TP1/Message Queue プログラム作成の手引」を参照してください。

MQPUT命令では，MQOO_PASS_IDENTITY_CONTEXTまたはこれに相当するオプションを指定してキューをオープンしておく必要があります。

MQPMO_PASS_ALL_CONTEXT

入力キューハンドルの全コンテキストを引き渡します。

関連するコンテキスト情報をメッセージに使用します。識別コンテキストおよび登録元コンテキストとして，Contextフィールドに指定したキューハンドルの情報を使用します。メッセージコンテキストおよびコンテキスト情報の制御については，マニュアル「TP1/Message Queue プログラム作成の手引」を参照してください。

MQPUT命令では，MQOO_PASS_ALL_CONTEXTまたはこれに相当するオプションを指定してキューをオープンしておく必要があります。

MQPMO_SET_IDENTITY_CONTEXT

アプリケーションが識別コンテキストを設定します。

関連するコンテキスト情報をメッセージに使用します。識別コンテキストとして，アプリケーションが指定したMQMD構造体の情報を設定します。登録元コンテキストは，キューマネジャによって，MQPMO_DEFAULT_CONTEXTと同様の方法で設定されます。メッセージコンテキストおよびコンテキスト情報の制御については，マニュアル「TP1/Message Queue プログラム作成の手引」を参照してください。

MQPUT命令では，MQOO_SET_IDENTITY_CONTEXTまたはこれに相当するオプションを指定してキューをオープンしておく必要があります。

MQPMO_SET_ALL_CONTEXT

アプリケーションが全コンテキストを設定します。

関連するコンテキスト情報をメッセージに使用します。識別コンテキストおよび登録元コンテキストとして，アプリケーションが指定したMQMD構造体の情報を設定します。メッセージコンテキストおよびコンテキスト情報の制御については，マニュアル「TP1/Message Queue プログラム作成の手引」を参照してください。

MQPUT命令では，MQOO_SET_ALL_CONTEXTを指定してキューをオープンしておく必要があります。

MQPMO_*_CONTEXTオプションは，一つだけ指定できます。これらのどれも指定しなかった場合，MQPMO_DEFAULT_CONTEXTオプションが仮定されます。

その他のオプション：

権限チェックおよびキューマネジャ停止時の動作を制御するオプションを次に示します。

MQPMO_ALTERNATE_USER_AUTHORITY

代替ユーザ識別子を使用します。

キューを利用するユーザの識別子として，アプリケーションを実行しているユーザ識別子ではなく，MQPUT1命令のObjDesc引数のAlternateUserIdの代替ユーザ識別子が使用されます。

これは，MQPUT1命令のときだけ指定できます。

MQPMO_FAIL_IF_QUIESCING

TP1/Message Queueでは意味がありません。

このオプションを指定しても，TP1/Message Queueの動作には影響しません。これは，アプリケーションの移植性を向上させるために定義されています。

デフォルトオプション：

ここまでで説明されたオプションを指定しない場合，次に示すオプションを使用できます。

MQPMO_NONE

オプションを指定しません。

このオプションは，ほかにオプションを指定しない場合に指定します。このほかのオプションには，どれも省略時の仮定値があります。MQPMO_NONEオプションは，プログラムのコーディングをわかりやすくするために定義されています。値としては0が定義されていますが，コーディングをわかりやすくする以外の目的はありません。

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

●　PutMsgRecFields（MQLONG型）　MQPMR構造体フィールドの存在

アプリケーションによって指定された登録メッセージレコードに，どんなMQPMR構造体フィールドが存在するか指示するように指定します。PutMsgRecFieldsフィールドは，メッセージが配布リストに登録されたときだけ使用されます。RecsPresentフィールドが0，またはPutMsgRecOffsetフィールドとPutMsgRecPtrフィールドが両方とも0の場合，このフィールドは無視されます。

存在するフィールドに対して，キューマネジャはそれぞれのあて先に対応する登録メッセージレコードのフィールドの値を使用します。存在しないフィールドに対しては，キューマネジャはMQMD構造体の初期値を使用します。

登録メッセージレコードにどんなフィールドがあるか示すために，フラグを一つ以上指定できます。指定できるフラグを次に示します。

MQPMRF_MSG_ID

メッセージ識別子フィールドが存在することを示します。

MQPMRF_CORREL_ID

相関識別子フィールドが存在することを示します。

MQPMRF_GROUP_ID

グループ識別子フィールドが存在することを示します。

MQPMRF_FEEDBACK

フィードバックフィールドが存在することを示します。

MQPMRF_ACCOUNTING_TOKEN

課金トークンフィールドが存在することを示します。

このフラグが指定された場合，MQPMO_SET_IDENTITY_CONTEXTまたはMQPMO_SET_ALL_CONTEXTがOptionsフィールドに指定されなければなりません。この条件が満たされない場合，MQRC_PMO_RECORD_FLAGS_ERRORの理由コードで失敗します。

MQPMR構造体のフィールドが存在しない場合，次のフラグを指定できます。

MQPMRF_NONE

登録メッセージレコードが存在しないことを示します。

この値が指定されると，RecsPresentフィールドは0でなければなりません。同時に，PutMsgRecOffsetフィールドおよびPutMsgRecPtrフィールドは，どちらも0でなければなりません。

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

次の場合，MQRC_PMO_RECORD_FLAGS_ERRORの理由コードで失敗します。

• PutMsgRecFieldsフィールドに不正なフラグが含まれている場合

• 登録メッセージレコードが指定されているが，PutMsgRecFieldsフィールドがMQPMRF_NONEである場合

これは入力用のフィールドです。

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

このフィールドは，Versionフィールドの値がMQPMO_VERSION_2以降の場合だけ有効です。

●　PutMsgRecOffset（MQLONG型）　最初の登録メッセージレコードまでのオフセット

MQPMO構造体の先頭から最初のMQPMR構造体登録メッセージレコードまでのバイトオフセットです。オフセットは正の場合も負の場合もあります。PutMsgRecOffsetフィールドは，配布リストにメッセージを登録するときだけ使用されます。RecsPresentフィールドが0の場合は無視されます。

配布リストにメッセージが登録されるとき，一つ以上のMQPMR構造体登録メッセージレコードの配列があて先ごとのメッセージ属性を指定するために指定されなければなりません。指定する属性を次に示します。

• メッセージ識別子

• 相関識別子

• グループ識別子

• フィードバック値

• 課金トークン

この属性をすべて指定する必要はありません。ただし，どの属性を選択しても，フィールドは正しい順序に指定されなければなりません。詳細については，この章の「MQPMR構造体　−　登録メッセージレコード」を参照してください。

配布リストのオープン時に，MQOD構造体によって指定されたオブジェクトレコードと同じ数の登録メッセージレコードが存在しなければなりません。登録メッセージレコードは，対応するオブジェクトレコードによって指定されるキューに対してメッセージ属性を与えます。配布リストのオープンに失敗したキューには，配列の適当な位置に配置される登録メッセージレコードが登録されなければなりません。その場合，メッセージ属性は無視されます。

登録メッセージレコードの数が，オブジェクトレコードの数と異なることがあります。オブジェクトレコードより登録メッセージレコードが少ない場合，登録メッセージレコードのないあて先のメッセージ属性は，メッセージ記述子MQMD構造体の対応するフィールドの属性が指定されます。オブジェクトレコードより登録メッセージレコードが多い場合，必要数以上のレコードは使用されません。ただし，使用されないレコードにもアクセスできなければなりません。

登録メッセージレコードの指定は任意です。ただし，RecsPresentフィールドがある場合は，指定しなければなりません。

登録メッセージレコードはMQOD構造体のオブジェクトレコードと同様の方法で指定できます。PutMsgRecOffsetフィールドのオフセットを指定するか，またはPutMsgRecPtrフィールドのアドレスを使用して指定してください。詳細は，この章の「MQDH構造体　−　配布ヘッダ」でObjectRecOffsetフィールドを参照してください。

PutMsgRecOffsetフィールドとPutMsgRecPtrフィールドは同時に使用できません。両方のフィールドが0以外の場合，MQRC_PUT_MSG_RECORDS_ERRORの理由コードで失敗します。

これは入力用のフィールドです。

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

このフィールドは，Versionフィールドの値がMQPMO_VERSION_2以降の場合だけ有効です。

●　PutMsgRecPtr（MQPTR型）　最初の登録メッセージレコードのアドレス

最初の登録メッセージレコードのアドレスです。PutMsgRecPtrフィールドは，配布リストにメッセージが登録されたときだけ使用されます。RecsPresentフィールドが0の場合は無視されます。

PutMsgRecPtrフィールドまたはPutMsgRecOffsetフィールドのどちらかを登録メッセージレコードを指定するのに使用できます。ただし，同時に使用できません。詳細については，「PutMsgRecOffsetフィールド」を参照してください。PutMsgRecPtrフィールドが使用されない場合は，ヌルポインタか0を設定しなければなりません。

これは入力用のフィールドです。

このフィールドの初期値は，ポインタをサポートしているプログラミング言語ではヌルポインタです。文字列の場合はヌル文字列です。

このフィールドは，Versionフィールドの値がMQPMO_VERSION_2以降の場合だけ有効です。

注意事項

プログラミング言語がポインタのデータ型をサポートしていないオペレーティングシステムでは，このフィールドは，初期値がすべてヌル文字列の，適当な長さのバイト文字列として宣言されます。

●　RecsPresent（MQLONG型）　登録メッセージレコード数または応答レコード数

アプリケーションによって指定されたMQPMR構造体の登録メッセージレコード数またはMQRR構造体の応答レコード数です。メッセージが配布リストに登録されたときだけ，この数が0より大きくなります。登録メッセージレコードまたは応答レコードは任意に選択できます。アプリケーションはどちらのレコードも指定しなかったり，どちらか一つのレコードだけ選択したりできます。ただし，アプリケーションが両方のレコードを指定する場合は，それぞれのRecsPresentフィールドのレコードを指定しなければなりません。

RecsPresentフィールドの値は，配布リストのあて先の数と同じである必要はありません。指定された値が必要数より大きい場合，必要数以上のレコードは使用されません。必要数より少ないレコードが指定された場合，登録メッセージレコードがないあて先のメッセージのプロパティ値は初期値を取ります。詳細については，「PutMsgRecOffsetフィールド」を参照してください。

RecsPresentフィールドの値が0より小さい，または0より大きいがメッセージは配布リストに登録されない場合，理由コードMQRC_RECS_PRESENT_ERRORで失敗します。

これは入力用のフィールドです。

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

このフィールドは，Versionフィールドの値がMQPMO_VERSION_2以降の場合だけ有効です。

●　ResolvedQMgrName（MQCHAR48型）　受信キューマネジャ名

ResolvedQNameのキューを定義しているキューマネジャの名称（実名）です。

ローカルキューマネジャが名称解決を実行したあとのあて先キューマネジャの名前です。返される名前は，ResolvedQNameフィールドに指定されたキューを保持するキューマネジャの名前です。ResolvedQMgrNameフィールドは，ローカルキューマネジャの名前になることがあります。

空白でない値が返されるのは，オブジェクトが単一のキューである場合だけです。オブジェクトが配布リストである場合，返される値は未定義です。

これは出力用のフィールドです。

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

このフィールドの初期値は，C言語ではヌル文字列です。そのほかのプログラミング言語では，48個の空白です。

●　ResolvedQName（MQCHAR48型）　受信キュー名

キューマネジャによって設定される出力用のフィールドです。

ローカルキューマネジャが名称解決を実行したあとのあて先キューの名前です。返される名前は，ResolvedQMgrNameフィールドに指定されたキューマネジャが保持するキューの名前です。キューがモデルキューでオープンされた場合，生成された動的ローカルキューの名称が返されます。

空白でない値が返されるのは，オブジェクトが単一のキューである場合だけです。オブジェクトが配布リストである場合，返される値は未定義です。

これは出力用のフィールドです。

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

このフィールドの初期値は，C言語ではヌル文字列です。そのほかのプログラミング言語では，48個の空白です。

●　ResponseRecOffset（MQLONG型）　最初の応答レコードまでのオフセット

MQPMO構造体の先頭から最初のMQRR構造体の応答レコードまでのバイトオフセットです。オフセットは，正の場合も負の場合もあります。ResponseRecOffsetフィールドは，メッセージが配布リストに登録されるときだけ使用されます。RecsPresentフィールドが0の場合は無視されます。

メッセージが配布リストに登録されるとき，一つ以上のMQRR構造体の応答レコードの配列が，メッセージの送信が成功しなかったキューと，その失敗の理由を特定するために指定されなければなりません。なお，メッセージの送信が成功しなかったキューはMQRR構造体のCompCodeフィールドに記述され，その失敗の理由はMQRR構造体のReasonフィールドに記述されます。

メッセージは，キューのオープンに失敗したか，登録操作が失敗したかのどちらかの理由で送信されていない可能性があります。キューマネジャが応答レコードを設定するのは，命令の結果が混在している場合だけです。例えば，次のような場合です。

• あるメッセージは送信に成功したが，ほかのメッセージが失敗している場合

• すべての送信が失敗し，その理由が異なる場合

この場合，MQRC_MULTIPLE_REASONSの理由コードが出現します。同じ理由コードがすべてのキューに適用される場合，応答レコードは設定されません。

配布リストがオープンされたとき，MQOD構造体によって指定されたオブジェクトレコードと同じ数の応答レコードが存在しなければなりません。応答レコードが必要であれば，対応するオブジェクトレコードによって指定されるキューに対する登録の完了コードと理由コードに設定されます。配布リストのオープンに失敗したキューには，配列の適当な位置に配置される応答レコードがなければなりません。その場合，登録操作ではなく，オープン操作の完了コードと理由コードが設定されます。

応答レコードの数がオブジェクトレコードの数と異なることがあります。

オブジェクトレコードよりも応答レコードが少ない場合，アプリケーションは登録に失敗したあて先や，失敗した理由のすべてを特定できなくなります。オブジェクトレコードよりも応答レコードが多い場合，必要数以上のレコードは使用されません。ただし，使用されないレコードにもアクセスできなければなりません。応答レコードは任意で指定できますが，指定された場合はRecsPresentフィールドがなければなりません。

応答レコードはオブジェクトレコードと同様に，ResponseRecOffsetフィールドのオフセットを指定するか，またはResponseRecPtrフィールドのアドレスを指定できます。指定方法については，この章の「MQOD構造体　−　オブジェクト記述子」でObjectRecOffsetフィールドを参照してください。ただし，ResponseRecOffsetフィールドとResponseRecPtrフィールドは同時に指定できません。どちらのフィールドも0以外の場合は，MQRC_RESPONSE_RECORDS_ERRORの理由コードで失敗します。

MQPUT1命令では，このフィールドがヌルポインタまたは0でなければなりません。応答情報を要求すると，オブジェクト記述子であるMQOD構造体によって指定される応答レコードに返されます。

これは入力用のフィールドです。

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

このフィールドは，Versionフィールドの値がMQPMO_VERSION_2以降の場合だけ有効です。

●　ResponseRecPtr（MQPTR型）　最初の応答レコードのアドレス

最初のMQRR構造体の応答レコードのアドレスです。ResponseRecPtrフィールドは，配布リストにメッセージが登録されたときだけ使用されます。RecsPresentフィールドが0の場合は無視されます。

ResponseRecPtrフィールドまたはResponseRecOffsetフィールドのどちらかを，応答レコードとして指定するために使用できます。ただし，同時に使用できません。詳細については，「ResponseRecOffsetフィールド」を参照してください。ResponseRecPtrフィールドを使用しない場合は，ヌルポインタかヌル文字列を設定しなければなりません。

MQPUT1命令では，このフィールドはヌルポインタまたは0でなければなりません。応答情報を要求すると，オブジェクト記述子MQOD構造体によって指定される応答レコードに返されます。

これは入力用のフィールドです。

このフィールドの初期値は，ポインタをサポートしているプログラミング言語ではヌルポインタです。文字列の場合はヌル文字列となります。

このフィールドは，Versionフィールドの値がMQPMO_VERSION_2以降の場合だけ有効です。

注意事項

プログラミング言語がポインタのデータ型をサポートしていないオペレーティングシステムでは，このフィールドは，初期値がヌル文字列の，適当な長さのバイト文字列として宣言されます。

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

次の値を取ります。

MQPMO_STRUC_ID

メッセージ登録オプションの構造体識別子

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

これは常に入力用のフィールドです。

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

●　Timeout（MQLONG型）　予備

予備のフィールドです。キューマネジャはこの内容を特に使用しません。

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

●　UnknownDestCount（MQLONG型）　リモートキューの数

配布リストの中で，リモートキューで受信されて，MQPUT命令またはMQPUT1命令による送信が成功したキューの数を示しています。

キューマネジャが配布リストに一時的に保持しているメッセージは，その配布リストに含まれるそれぞれのあて先の数としてカウントされます。このフィールドは配布リストではない単一のキューへの登録時にも設定されます。

これは出力用のフィールドです。

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

なお，このフィールドは，VersionフィールドがMQPMO_VERSION_2より前の場合は設定されません。

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

次の値を取ります。

MQPMO_VERSION_1

バージョン1のメッセージ登録オプションの構造体バージョン番号

このバージョンはすべての環境でサポートされています。

MQPMO_VERSION_2

バージョン2のメッセージ登録オプションの構造体バージョン番号

MQPMO_VERSION_2以降の構造体にだけ存在するフィールドについては，そのことがフィールドの説明に記載されています。次に示す定数は，現在のバージョンのバージョン番号を指定します。

MQPMO_CURRENT_VERSION

現在のバージョンのメッセージ登録オプションの構造体バージョン番号

これは常に入力用のフィールドです。

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