MQPMO構造体 - メッセージ登録オプション
MQPMO構造体は,MQPUT命令およびMQPUT1命令の入出力用の引数です。次のフィールドから構成されます。
フィールド(データタイプ) | 内容 | 初期値 |
---|---|---|
StrucId(MQCHAR4型) | 構造体識別子 | MQPMO_STRUC_ID |
Version(MQLONG型) | 構造体バージョン番号 | MQPMO_VERSION_1 |
Options(MQLONG型) | 登録オプション | MQPMO_NONE |
Timeout(MQLONG型) | (予備) | -1 |
Context(MQHOBJ型) | コンテキスト | 0 |
KnownDestCount(MQLONG型) | ローカルキューの数 | 0 |
UnknownDestCount(MQLONG型) | リモートキューの数 | 0 |
InvalidDestCount(MQLONG型) | 送信に失敗したキューの数 | 0 |
ResolvedQName(MQCHAR48型) | 受信キュー名 | ヌル文字列/空白 |
ResolvedQMgrName(MQCHAR48型) | 受信キューマネジャ名 | ヌル文字列/空白 |
RecsPresent(MQLONG型)※ | 登録メッセージレコード数または応答レコード数 | 0 |
PutMsgRecFields(MQLONG型)※ | MQPMR構造体フィールドの存在 | MQPMRF_NONE |
PutMsgRecOffset(MQLONG型)※ | 最初の登録メッセージレコードまでのオフセット | 0 |
ResponseRecOffset(MQLONG型)※ | 最初の応答レコードまでのオフセット | 0 |
PutMsgRecPtr(MQPTR型)※ | 最初の登録メッセージレコードのアドレス | ヌルポインタ/ヌル文字列 |
ResponseRecPtr(MQPTR型)※ | 最初の応答レコードのアドレス | ヌルポインタ/ヌル文字列 |
概要
目的
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型) 送信に失敗したキューの数
配布リスト中のキューの中で,送信できなかったメッセージの数です。オープンは成功したが登録に失敗したキューや,オープンに失敗したキューの数も含まれます。このフィールドは配布リストではない単一のキューへの登録時にも設定されます。
これは出力用のフィールドです。
このフィールドの初期値は0です。
なお,このフィールドは,VersionフィールドがMQPMO_VERSION_2より前の場合は設定されません。
● KnownDestCount(MQLONG型) ローカルキューの数
配布リストの中で,MQPUT命令またはMQPUT1命令による,ローカルキューであるキューへの送信が成功したキューの数を示しています。ローカルな転送キューが最初のメッセージ登録に使用された場合も,値はリモートキューで受信されるキューは含みません。このフィールドは配布リストではない単一のキューへの登録時にも設定されます。
これは出力用のフィールドです。
このフィールドの初期値は0です。
なお,このフィールドは,VersionフィールドがMQPMO_VERSION_2より前の場合は設定されません。
● Options(MQLONG型) 登録オプション
MQPUT命令およびMQPUT1命令の動作を制御します。
指定できるオプションを説明します。なお,指定しなくてもかまいません。二つ以上の値を指定する場合は,次のどちらかに従ってください。
同時に指定できない組み合わせは,そのつど示します。それ以外の組み合わせは自由です。オプションおよびその指定方法の一覧については,「付録A 命令および引数の一覧」を参照してください。
同期点オプション:
MQPUTまたはMQPUT1命令のトランザクションへの参加に関連するオプションを次に示します。
キューマネジャの SyncPoint属性 | MQPUT/MQPUT1 命令の呼び出し位置 | MQPUT/MQPUT1命令の 同期点のオプション | ||
---|---|---|---|---|
MQPMO_ SYNCPOINT | MQPMO_ NO_SYNCPOINT | 省略 | ||
MQSP_AVAILABLE | トランザクション内 | 1 | 2 | 1 |
トランザクション外 | × | 2 | 2 | |
MQSP_NOT_AVAILABLE | トランザクション内 | × | 2 | × |
トランザクション外 | × | 2 | 2 |
メッセージ識別子および相関識別子オプション:
キューマネジャに新しいメッセージ識別子または相関識別子を生成させるオプションを次に示します。
グループとセグメントに関するオプション:
グループ内のメッセージおよび論理メッセージのセグメントの処理に関連するオプションを次に示します。オプションを理解するために,次の用語について説明します。
次に,メッセージが,MQGET命令で返却される方法を制御する個々のオプションについて説明します。
指定するオプション | 命令に先行するグループと論理メッセージの状態 | キューマネジャが使用する値 | ||||||
---|---|---|---|---|---|---|---|---|
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 |
× | × | × | ○ | - | - |
| 1 | 0 |
× | × | ○ | - | - | - |
| 1 | フィールドの値 |
× | ○ | × | - | - | - |
| フィールドの値 | 0 |
× | ○ | ○ | - | - | - |
| フィールドの値 | フィールドの値 |
実行時の命令 | 直前の命令が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 |
コンテキストオプション:
メッセージコンテキストの処理を制御するオプションを次に示します。
MQMD構造体のフィールド | 値 |
---|---|
UserIdentifier | "OPENTP1"またはAlternateUserId(環境に依存する値) |
AccountingToken | MQACT_NONE(環境に依存する値) |
ApplIdentityData | 空白 |
PutApplType | MQAT_OPEN_TP1(環境に依存する値) |
PutApplName | ユーザサーバ名(SUP名,SPP名)(環境に依存する値) |
PutDate | メッセージを登録した日付 |
PutTime | メッセージを登録した時刻 |
ApplOriginData | 空白 |
MQPMO_*_CONTEXTオプションは,一つだけ指定できます。これらのどれも指定しなかった場合,MQPMO_DEFAULT_CONTEXTオプションが仮定されます。
その他のオプション:
権限チェックおよびキューマネジャ停止時の動作を制御するオプションを次に示します。
デフォルトオプション:
ここまでで説明されたオプションを指定しない場合,次に示すオプションを使用できます。
このフィールドの初期値はMQPMO_NONEです。
● PutMsgRecFields(MQLONG型) MQPMR構造体フィールドの存在
アプリケーションによって指定された登録メッセージレコードに,どんなMQPMR構造体フィールドが存在するか指示するように指定します。PutMsgRecFieldsフィールドは,メッセージが配布リストに登録されたときだけ使用されます。RecsPresentフィールドが0,またはPutMsgRecOffsetフィールドとPutMsgRecPtrフィールドが両方とも0の場合,このフィールドは無視されます。
存在するフィールドに対して,キューマネジャはそれぞれのあて先に対応する登録メッセージレコードのフィールドの値を使用します。存在しないフィールドに対しては,キューマネジャはMQMD構造体の初期値を使用します。
登録メッセージレコードにどんなフィールドがあるか示すために,フラグを一つ以上指定できます。指定できるフラグを次に示します。
MQPMR構造体のフィールドが存在しない場合,次のフラグを指定できます。
次の場合,MQRC_PMO_RECORD_FLAGS_ERRORの理由コードで失敗します。
これは入力用のフィールドです。
このフィールドの初期値は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です。
● Timeout(MQLONG型) 予備
予備のフィールドです。キューマネジャはこの内容を特に使用しません。
このフィールドの初期値は-1です。
● UnknownDestCount(MQLONG型) リモートキューの数
配布リストの中で,リモートキューで受信されて,MQPUT命令またはMQPUT1命令による送信が成功したキューの数を示しています。
キューマネジャが配布リストに一時的に保持しているメッセージは,その配布リストに含まれるそれぞれのあて先の数としてカウントされます。このフィールドは配布リストではない単一のキューへの登録時にも設定されます。
これは出力用のフィールドです。
このフィールドの初期値は0です。
なお,このフィールドは,VersionフィールドがMQPMO_VERSION_2より前の場合は設定されません。
● Version(MQLONG型) 構造体バージョン番号
次の値を取ります。
MQPMO_VERSION_2以降の構造体にだけ存在するフィールドについては,そのことがフィールドの説明に記載されています。次に示す定数は,現在のバージョンのバージョン番号を指定します。
これは常に入力用のフィールドです。
このフィールドの初期値はMQPMO_VERSION_1です。