MQPUT1命令 − 1メッセージの登録
機能
MQPUT1命令で,一つのメッセージをキューへ登録できます。キューはオープンされている必要がありません。
形式
C言語の場合
MQPUT1(MQHCONN Hconn, PMQVOID ObjDesc, PMQVOID MsgDesc, PMQVOID PutMsgOpts,MQLONG BufferLength, PMQVOID Buffer, PMQLONG CompCode, PMQLONG Reason)
COBOL言語の場合
CALL 'MQPUT1' USING HCONN, OBJDESC, MSGDESC, PUTMSGOPTS, BUFFERLENGTH, BUFFER, COMPCODE, REASON.
引数
● Hconn(MQHCONN型) −input
コネクションハンドルです。
キューマネジャへの接続を示すハンドルです。MQCONN命令の戻り値を指定してください。
● ObjDesc(MQOD構造体) −input
オブジェクト記述子です。
登録するキューを識別する構造体です。詳細については,「1. データタイプ」の「MQOD構造体 − オブジェクト記述子」を参照してください。
モデルキューは指定できません。
● MsgDesc(MQMD構造体) −input/output
メッセージ記述子です。
送信するメッセージの属性を記述する構造体です。また,登録後のメッセージに関する情報が返されます。
詳細については,「1. データタイプ」の「MQMD構造体 − メッセージ記述子」を参照してください。
アプリケーションがバージョン1のMQMD構造体を指定すると,返却されるメッセージは,バージョン2のMQMD構造体にだけ存在するフィールドの値を指定するために,アプリケーションメッセージデータの前にMQMDE構造体を付加できます。そのとき,MQMDE構造体が存在することを示すために,MQMD構造体のFormatフィールドには,MQFMT_MD_EXTENSIONを設定しなければなりません。
詳細については,「1. データタイプ」の「MQMDE構造体 − メッセージ記述子の拡張」を参照してください。
● PutMsgOpts(MQPMO構造体) −input/output
メッセージ登録オプションです。
詳細については,「1. データタイプ」の「MQPMO構造体 − メッセージ登録オプション」を参照してください。
● BufferLength(MQLONG型) −input
メッセージデータを格納したバッファのバイト長です。
0も指定できます。このとき,アプリケーションデータのないメッセージを登録するものとみなされます。
あて先キューがローカルキューの場合,またはローカルキューの別名を使用している場合は,ローカルキューまたはキューマネジャのMaxMsgLength属性のうち,小さい方の値を超えて指定できません。
あて先キューがリモートキューの場合,またはリモートキューの別名を使用している場合は,次に示すローカルキューまたはキューマネジャのMaxMsgLength属性のうち,小さい方の値を超えて指定できません。
-
ローカルキューマネジャで一時的に格納するために使用される転送キュー
-
ローカルキューからあて先キューまでの経路で仲介するキューマネジャで使用される転送キュー
-
あて先キューマネジャで使用されるあて先キュー
なお,メッセージが転送キューに格納されるとき,メッセージに付加情報が追加されます。このため,送信できるアプリケーションデータの量が少なくなります。BufferLength引数の値を決めるときは,転送キューのMaxMsgLength属性の値からMQ_MSG_HEADER_LENGTHのバイト数を引いた値を参考にしてください。
- 注意事項
-
上記の1.の場合だけ,メッセージの登録直後にバッファ長のエラー(理由コードMQRC_MSG_TOO_BIG_FOR_QまたはMQRC_MSG_TOO_BIG_FOR_Q_MGR)が判明します。2.,3.の場合は,登録直後はエラーが判明しません。2.,3.でエラーが判明した場合,仲介するキューマネジャまたはあて先キューマネジャのデッドレターキューに,メッセージが転送されます。送信側で要求している場合は,エラー発生時に報告メッセージが生成されます。
● Buffer(MQBYTE型×BufferLength) −input
メッセージデータを格納したバッファです。バッファには,メッセージ中のデータに適したバウンダリ調整が必要です。多くのメッセージ(MQヘッダ構造体のあるメッセージを含む)には4バイト単位の調整が適していますが,より厳しい調整が必要なメッセージもあります。例えば,64ビット2進整数を含めるメッセージには8バイト単位のバウンダリ調整が必要です。
バッファ内に文字または数値がある場合,MsgDesc引数のCodedCharSetIdフィールドとEncodingフィールドに,適切な値を指定してください。これらの値によって,受信側でデータを適切な文字セットとマシンコード形式に変換できます。
- 注意事項
-
MQPUT1命令のそのほかの引数は,ローカルキューマネジャの文字セットとマシンコード形式,つまり,ローカルキューのCodedCharSetId属性とMQENC_NATIVEで指定してください。
C言語では,この引数をvoid型のポインタとして指定します。したがって,どんなデータタイプのアドレスでも,引数として指定できます。
BufferLength引数で0を指定した場合,Buffer引数は参照されません。したがって,C言語のプログラムでは,この引数のアドレスとしてヌルを指定できます。
● CompCode(MQLONG型) −output
完了コードです。
次のどれかが返されます。
-
MQCC_OK:成功
-
MQCC_WARNING:警告(一部成功)
-
MQCC_FAILED:失敗
● Reason(MQLONG型) −output
理由コードです。
CompCode引数がMQCC_OKの場合
理由コード |
数値 |
意味 |
---|---|---|
MQRC_NONE |
0 |
理由コードはありません。 |
CompCode引数がMQCC_WARNINGの場合
理由コード |
数値 |
意味 |
---|---|---|
MQRC_MULTIPLE_REASONS |
2136 |
複数の理由コードが返されました。 |
MQRC_PRIORITY_EXCEEDS_MAXIMUM |
2049 |
メッセージ優先度が最大値を超えています。 |
MQRC_UNKNOWN_REPORT_OPTION |
2104 |
メッセージ記述子中の報告オプションを認識できません。 |
CompCode引数がMQCC_FAILEDの場合
理由コード |
数値 |
意味 |
---|---|---|
MQRC_ALIAS_BASE_Q_TYPE_ERROR |
2001 |
別名キューのベースキューのタイプが不正です。 |
MQRC_BUFFER_ERROR |
2004 |
バッファの引数が不正です。 |
MQRC_BUFFER_LENGTH_ERROR |
2005 |
バッファ長の引数が不正です。 |
MQRC_CLUSTER_PUT_INHIBITED |
2268 |
クラスタ内のすべてのキューに対して登録が禁止されています。 |
MQRC_CLUSTER_RESOLUTION_ERROR |
2189 |
クラスタ名称の解決に失敗しました。 |
MQRC_CLUSTER_RESOURCE_ERROR |
2269 |
クラスタリソースのエラーです。 |
MQRC_CONTEXT_HANDLE_ERROR |
2097 |
参照先のキューハンドルにコンテキストが保存されていません。 |
MQRC_CONTEXT_NOT_AVAILABLE |
2098 |
参照先のキューハンドルのコンテキストが不正です。 |
MQRC_DEF_XMIT_Q_TYPE_ERROR |
2198 |
省略時の転送キューがローカルキューではありません。 |
MQRC_DEF_XMIT_Q_USAGE_ERROR |
2199 |
省略時の転送キューの使用方法に誤りがあります。 |
MQRC_DH_ERROR |
2135 |
配布リスト構造体が不正です。 |
MQRC_EXPIRY_ERROR |
2013 |
メッセージ保持時間が不正です。 |
MQRC_FEEDBACK_ERROR |
2014 |
報告メッセージ返答コードが不正です。 |
MQRC_HANDLE_NOT_AVAILABLE |
2017 |
現在そのハンドルは有効ではありません。 |
MQRC_HCONN_ERROR |
2018 |
コネクションハンドルが不正です。 |
MQRC_MD_ERROR |
2026 |
メッセージ記述子が不正です。 |
MQRC_MDE_ERROR |
2248 |
メッセージ記述子の拡張子が不正です。 |
MQRC_MISSING_REPLY_TO_Q |
2027 |
応答キューがありません。 |
MQRC_MSG_FLAGS_ERROR |
2249 |
メッセージフラグが不正です。 |
MQRC_MSG_SEQ_NUMBER_ERROR |
2250 |
メッセージシーケンス番号が不正です。 |
MQRC_MSG_TOO_BIG_FOR_Q |
2030 |
メッセージ長がキューに定義された最大値を超えています。 |
MQRC_MSG_TYPE_ERROR |
2029 |
メッセージ記述子中のメッセージタイプが不正です。 |
MQRC_MULTIPLE_REASONS |
2136 |
複数の理由コードが返されます。 |
MQRC_NO_DESTINATIONS_AVAILABLE |
2270 |
利用可能なあて先キューが存在しません。 |
MQRC_OBJECT_DAMAGED |
2101 |
オブジェクトが破損しています。 |
MQRC_OBJECT_NAME_ERROR |
2152 |
オブジェクト名が不正です。 |
MQRC_OBJECT_Q_MGR_NAME_ERROR |
2153 |
オブジェクトキューマネジャ名が不正です。 |
MQRC_OBJECT_RECORDS_ERROR |
2155 |
オブジェクトレコードが不正です。 |
MQRC_OBJECT_TYPE_ERROR |
2043 |
オブジェクトタイプが不正です。 |
MQRC_OD_ERROR |
2044 |
オブジェクト記述子の構造体が不正です。 |
MQRC_OFFSET_ERROR |
2251 |
メッセージセグメントのオフセットが不正です。 |
MQRC_OPTIONS_ERROR |
2046 |
オプションが不正です。または,指定されていません。 |
MQRC_ORIGINAL_LENGTH_ERROR |
2252 |
元の長さが不正です。 |
MQRC_PERSISTENCE_ERROR |
2047 |
メッセージ永続性が不正です。 |
MQRC_PERSISTENT_NOT_ALLOWED |
2048 |
キューは永続メッセージをサポートしていません。 |
MQRC_PMO_ERROR |
2173 |
メッセージ登録オプションの構造体が不正です。 |
MQRC_PMO_RECORD_FLAGS_ERROR |
2158 |
登録メッセージレコードのフラグが不正です。 |
MQRC_PRIORITY_ERROR |
2050 |
メッセージ優先度が不正です。 |
MQRC_PUT_INHIBITED |
2051 |
指定されたキューへの登録は禁止されています。 |
MQRC_PUT_MSG_RECORDS_ERROR |
2159 |
登録メッセージレコードが不正です。 |
MQRC_Q_DELETED |
2052 |
キューが削除されています。 |
MQRC_Q_FULL |
2053 |
キューが満杯です。 |
MQRC_Q_SPACE_NOT_AVAILABLE |
2056 |
キューに対応するディスクに空き領域がありません。 |
MQRC_Q_TYPE_ERROR |
2057 |
キュータイプが不正です。 |
MQRC_RECS_PRESENT_ERROR |
2154 |
存在するレコード数が不正です。 |
MQRC_REMOTE_Q_NAME_ERROR |
2184 |
リモートキュー名が不正です。 |
MQRC_REPORT_OPTIONS_ERROR |
2061 |
メッセージ記述子中の報告オプションが不正です。 |
MQRC_RESOURCE_PROBLEM |
2102 |
システム資源が不足しています。 |
MQRC_RESPONSE_RECORDS_ERROR |
2156 |
応答レコードが不正です。 |
MQRC_SEGMENT_LENGTH_ZERO |
2253 |
メッセージセグメントのデータ長が0です。 |
MQRC_STORAGE_NOT_AVAILABLE |
2071 |
記憶容量が不足しています。 |
MQRC_SYNCPOINT_NOT_AVAILABLE |
2072 |
同期点処理はできません。 |
MQRC_UNEXPECTED_ERROR |
2195 |
予期しないエラーが発生しました。 |
MQRC_UNKNOWN_ALIAS_BASE_Q |
2082 |
別名キューのベースキューを認識できません。 |
MQRC_UNKNOWN_DEF_XMIT_Q |
2197 |
省略時の転送キューを認識できません。 |
MQRC_UNKNOWN_OBJECT_NAME |
2085 |
オブジェクト名を認識できません。 |
MQRC_UNKNOWN_OBJECT_Q_MGR |
2086 |
オブジェクトのキューマネジャを認識できません。 |
MQRC_UNKNOWN_REMOTE_Q_MGR |
2087 |
リモートキューマネジャを認識できません。 |
MQRC_UNKNOWN_XMIT_Q |
2196 |
転送キューを認識できません。 |
MQRC_UOW_NOT_AVAILABLE |
2255 |
コミット単位でキューマネジャを使用できません。 |
MQRC_WRONG_MD_VERSION |
2257 |
MQMD構造体に指定されたバージョンが不正です。 |
MQRC_XMIT_Q_TYPE_ERROR |
2091 |
転送キューがローカルキューではありません。 |
MQRC_XMIT_Q_USAGE_ERROR |
2092 |
転送キューの使用方法に誤りがあります。 |
詳細は,「付録B.2 理由コード」を参照してください。
注意事項
-
キューへメッセージを登録する命令には,MQPUT命令とMQPUT1命令の二つがあります。これらの命令は,状況に応じて使い分けてください。
-
MQPUT命令は,同じキューへ複数のメッセージを登録するときに使用します。
この方法では,始めにMQOO_OUTPUTオプションを指定してMQOPEN命令を呼び出します。次に,MQPUT命令を一回またはそれ以上呼び出してメッセージを登録してください。最後にMQCLOSE命令を呼び出して,キューをクローズします。この方法でメッセージを登録すると,MQPUT1命令を繰り返して呼び出すよりも効率的です。
-
MQPUT1命令は,あるキューへメッセージを一つだけ登録するときに使用します。
この方法では,一回の呼び出しでMQOPEN命令,MQPUT命令,およびMQCLOSE命令を兼ねます。このため,命令の呼び出しを少なくできます。
-
-
アプリケーションがメッセージグループを使用しないで,連続するメッセージを同じキューに登録する場合,特定の条件が満たされれば,メッセージの順序が保持されます。しかし,ほとんどの環境ではMQPUT1命令はこれらの条件を満たさず,メッセージの順序は保持されません。これらの環境では,代わりにMQPUT命令を使用する必要があります。詳細については,この章の「MQPUT命令 − メッセージの登録」の「注意事項」を参照してください。
-
MQPUT1命令は,メッセージを配布リストに登録するのに使用できます。配布リストの登録については,この章の「MQOPEN命令 − オブジェクトのオープン」および「MQPUT命令 − メッセージの登録」の注意事項を参照してください。
次に,MQPUT1命令に特有の注意事項を示します。
-
MQRR構造体の応答レコードがアプリケーションによって指定されるとき,その応答レコードはMQOD構造体を使用して指定されなければなりません。なお,MQPMO構造体によって指定することはできません。
-
理由コードMQRC_OPEN_FAILEDは,MQPUT1命令では応答レコードに返されません。キューのオープンに失敗すると,そのキューの応答レコードはオープン操作から結果までの理由コードを保持します。キューのオープン操作がMQCC_WARNINGの完了コードで成功すると,そのキューの応答レコードの完了コードと理由コードは,登録操作の結果である完了コードと理由コードで置き換えられます。MQOPEN命令およびMQPUT命令と同様に,キューマネジャは結果が配布リストのすべてのキューで異なるときだけ,応答レコードが指定されている場合は応答レコードを設定します。これは,MQRC_MULTIPLE_REASONSの理由コードで完了することで示されます。
-
MQPUT1命令がメッセージを配布リストに登録するのに使用されると,アプリケーションがハンドルの最大数,つまり,キューマネジャのMaxHandles属性を超えているかチェックするときに,一つのハンドルとしてカウントされます。これは,配布リストのあて先数とは関係ありません。
ただし,MQOPEN命令が使用されると,配布リストのおのおののあて先が,別々のハンドルとしてカウントされます。
-
-
MQPUT1命令がクラスタキューにメッセージを登録するために使用された場合,MQOPEN命令でMQOO_BIND_NOT_FIXEDが指定されたように動作します。
-
メッセージがアプリケーションメッセージデータの先頭に,一つ以上のMQヘッダ構造体を付けて登録されると,キューマネジャはこれらが正しいか確認するために,ヘッダ構造体をチェックします。詳細については,この章の「MQPUT命令 − メッセージの登録」の注意事項を参照してください。
-
CompCode引数を参照したときに一つ以上の警告が発生していると,返却される理由コードの最初のものは次に示すコードのどれかになります。
MQRC_MULTIPLE_REASONS
MQRC_INCOMPLETE_MSG
MQRC_INCOMPLETE_GROUP
MQRC_PRIORITY_EXCEEDS_MAXIMUM
MQRC_UNKNOWN_REPORT_OPTION