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属性のうち,小さい方の値を超えて指定できません。

  1. ローカルキューマネジャで一時的に格納するために使用される転送キュー
  2. ローカルキューからあて先キューまでの経路で仲介するキューマネジャで使用される転送キュー
  3. あて先キューマネジャで使用されるあて先キュー

なお,メッセージが転送キューに格納されるとき,メッセージに付加情報が追加されます。このため,送信できるアプリケーションデータの量が少なくなります。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

完了コードです。

次のどれかが返されます。

● Reason(MQLONG型) -output

理由コードです。

CompCode引数がMQCC_OKの場合

理由コード数値意味
MQRC_NONE0理由コードはありません。

CompCode引数がMQCC_WARNINGの場合

理由コード数値意味
MQRC_MULTIPLE_REASONS2136複数の理由コードが返されました。
MQRC_PRIORITY_EXCEEDS_MAXIMUM2049メッセージ優先度が最大値を超えています。
MQRC_UNKNOWN_REPORT_OPTION2104メッセージ記述子中の報告オプションを認識できません。

CompCode引数がMQCC_FAILEDの場合

理由コード数値意味
MQRC_ALIAS_BASE_Q_TYPE_ERROR2001別名キューのベースキューのタイプが不正です。
MQRC_BUFFER_ERROR2004バッファの引数が不正です。
MQRC_BUFFER_LENGTH_ERROR2005バッファ長の引数が不正です。
MQRC_CLUSTER_PUT_INHIBITED2268クラスタ内のすべてのキューに対して登録が禁止されています。
MQRC_CLUSTER_RESOLUTION_ERROR2189クラスタ名称の解決に失敗しました。
MQRC_CLUSTER_RESOURCE_ERROR2269クラスタリソースのエラーです。
MQRC_CONTEXT_HANDLE_ERROR2097参照先のキューハンドルにコンテキストが保存されていません。
MQRC_CONTEXT_NOT_AVAILABLE2098参照先のキューハンドルのコンテキストが不正です。
MQRC_DEF_XMIT_Q_TYPE_ERROR2198省略時の転送キューがローカルキューではありません。
MQRC_DEF_XMIT_Q_USAGE_ERROR2199省略時の転送キューの使用方法に誤りがあります。
MQRC_DH_ERROR2135配布リスト構造体が不正です。
MQRC_EXPIRY_ERROR2013メッセージ保持時間が不正です。
MQRC_FEEDBACK_ERROR2014報告メッセージ返答コードが不正です。
MQRC_HANDLE_NOT_AVAILABLE2017現在そのハンドルは有効ではありません。
MQRC_HCONN_ERROR2018コネクションハンドルが不正です。
MQRC_MD_ERROR2026メッセージ記述子が不正です。
MQRC_MDE_ERROR2248メッセージ記述子の拡張子が不正です。
MQRC_MISSING_REPLY_TO_Q2027応答キューがありません。
MQRC_MSG_FLAGS_ERROR2249メッセージフラグが不正です。
MQRC_MSG_SEQ_NUMBER_ERROR2250メッセージシーケンス番号が不正です。
MQRC_MSG_TOO_BIG_FOR_Q2030メッセージ長がキューに定義された最大値を超えています。
MQRC_MSG_TYPE_ERROR2029メッセージ記述子中のメッセージタイプが不正です。
MQRC_MULTIPLE_REASONS2136複数の理由コードが返されます。
MQRC_NO_DESTINATIONS_AVAILABLE2270利用可能なあて先キューが存在しません。
MQRC_OBJECT_DAMAGED2101オブジェクトが破損しています。
MQRC_OBJECT_NAME_ERROR2152オブジェクト名が不正です。
MQRC_OBJECT_Q_MGR_NAME_ERROR2153オブジェクトキューマネジャ名が不正です。
MQRC_OBJECT_RECORDS_ERROR2155オブジェクトレコードが不正です。
MQRC_OBJECT_TYPE_ERROR2043オブジェクトタイプが不正です。
MQRC_OD_ERROR2044オブジェクト記述子の構造体が不正です。
MQRC_OFFSET_ERROR2251メッセージセグメントのオフセットが不正です。
MQRC_OPTIONS_ERROR2046オプションが不正です。または,指定されていません。
MQRC_ORIGINAL_LENGTH_ERROR2252元の長さが不正です。
MQRC_PERSISTENCE_ERROR2047メッセージ永続性が不正です。
MQRC_PERSISTENT_NOT_ALLOWED2048キューは永続メッセージをサポートしていません。
MQRC_PMO_ERROR2173メッセージ登録オプションの構造体が不正です。
MQRC_PMO_RECORD_FLAGS_ERROR2158登録メッセージレコードのフラグが不正です。
MQRC_PRIORITY_ERROR2050メッセージ優先度が不正です。
MQRC_PUT_INHIBITED2051指定されたキューへの登録は禁止されています。
MQRC_PUT_MSG_RECORDS_ERROR2159登録メッセージレコードが不正です。
MQRC_Q_DELETED2052キューが削除されています。
MQRC_Q_FULL2053キューが満杯です。
MQRC_Q_SPACE_NOT_AVAILABLE2056キューに対応するディスクに空き領域がありません。
MQRC_Q_TYPE_ERROR2057キュータイプが不正です。
MQRC_RECS_PRESENT_ERROR2154存在するレコード数が不正です。
MQRC_REMOTE_Q_NAME_ERROR2184リモートキュー名が不正です。
MQRC_REPORT_OPTIONS_ERROR2061メッセージ記述子中の報告オプションが不正です。
MQRC_RESOURCE_PROBLEM2102システム資源が不足しています。
MQRC_RESPONSE_RECORDS_ERROR2156応答レコードが不正です。
MQRC_SEGMENT_LENGTH_ZERO2253メッセージセグメントのデータ長が0です。
MQRC_STORAGE_NOT_AVAILABLE2071記憶容量が不足しています。
MQRC_SYNCPOINT_NOT_AVAILABLE2072同期点処理はできません。
MQRC_UNEXPECTED_ERROR2195予期しないエラーが発生しました。
MQRC_UNKNOWN_ALIAS_BASE_Q2082別名キューのベースキューを認識できません。
MQRC_UNKNOWN_DEF_XMIT_Q2197省略時の転送キューを認識できません。
MQRC_UNKNOWN_OBJECT_NAME2085オブジェクト名を認識できません。
MQRC_UNKNOWN_OBJECT_Q_MGR2086オブジェクトのキューマネジャを認識できません。
MQRC_UNKNOWN_REMOTE_Q_MGR2087リモートキューマネジャを認識できません。
MQRC_UNKNOWN_XMIT_Q2196転送キューを認識できません。
MQRC_UOW_NOT_AVAILABLE2255コミット単位でキューマネジャを使用できません。
MQRC_WRONG_MD_VERSION2257MQMD構造体に指定されたバージョンが不正です。
MQRC_XMIT_Q_TYPE_ERROR2091転送キューがローカルキューではありません。
MQRC_XMIT_Q_USAGE_ERROR2092転送キューの使用方法に誤りがあります。

詳細は,「付録B.2 理由コード」を参照してください。

注意事項

  1. キューへメッセージを登録する命令には,MQPUT命令とMQPUT1命令の二つがあります。これらの命令は,状況に応じて使い分けてください。
    • MQPUT命令は,同じキューへ複数のメッセージを登録するときに使用します。
      この方法では,始めにMQOO_OUTPUTオプションを指定してMQOPEN命令を呼び出します。次に,MQPUT命令を一回またはそれ以上呼び出してメッセージを登録してください。最後にMQCLOSE命令を呼び出して,キューをクローズします。この方法でメッセージを登録すると,MQPUT1命令を繰り返して呼び出すよりも効率的です。
    • MQPUT1命令は,あるキューへメッセージを一つだけ登録するときに使用します。
      この方法では,一回の呼び出しでMQOPEN命令,MQPUT命令,およびMQCLOSE命令を兼ねます。このため,命令の呼び出しを少なくできます。
  2. アプリケーションがメッセージグループを使用しないで,連続するメッセージを同じキューに登録する場合,特定の条件が満たされれば,メッセージの順序が保持されます。しかし,ほとんどの環境ではMQPUT1命令はこれらの条件を満たさず,メッセージの順序は保持されません。これらの環境では,代わりにMQPUT命令を使用する必要があります。詳細については,この章の「MQPUT命令 - メッセージの登録」の「注意事項」を参照してください。
  3. MQPUT1命令は,メッセージを配布リストに登録するのに使用できます。配布リストの登録については,この章の「MQOPEN命令 - オブジェクトのオープン」および「MQPUT命令 - メッセージの登録」の注意事項を参照してください。
    次に,MQPUT1命令に特有の注意事項を示します。
    • MQRR構造体の応答レコードがアプリケーションによって指定されるとき,その応答レコードはMQOD構造体を使用して指定されなければなりません。なお,MQPMO構造体によって指定することはできません。
    • 理由コードMQRC_OPEN_FAILEDは,MQPUT1命令では応答レコードに返されません。キューのオープンに失敗すると,そのキューの応答レコードはオープン操作から結果までの理由コードを保持します。キューのオープン操作がMQCC_WARNINGの完了コードで成功すると,そのキューの応答レコードの完了コードと理由コードは,登録操作の結果である完了コードと理由コードで置き換えられます。MQOPEN命令およびMQPUT命令と同様に,キューマネジャは結果が配布リストのすべてのキューで異なるときだけ,応答レコードが指定されている場合は応答レコードを設定します。これは,MQRC_MULTIPLE_REASONSの理由コードで完了することで示されます。
    • MQPUT1命令がメッセージを配布リストに登録するのに使用されると,アプリケーションがハンドルの最大数,つまり,キューマネジャのMaxHandles属性を超えているかチェックするときに,一つのハンドルとしてカウントされます。これは,配布リストのあて先数とは関係ありません。
    ただし,MQOPEN命令が使用されると,配布リストのおのおののあて先が,別々のハンドルとしてカウントされます。
  4. MQPUT1命令がクラスタキューにメッセージを登録するために使用された場合,MQOPEN命令でMQOO_BIND_NOT_FIXEDが指定されたように動作します。
  5. メッセージがアプリケーションメッセージデータの先頭に,一つ以上のMQヘッダ構造体を付けて登録されると,キューマネジャはこれらが正しいか確認するために,ヘッダ構造体をチェックします。詳細については,この章の「MQPUT命令 - メッセージの登録」の注意事項を参照してください。
  6. CompCode引数を参照したときに一つ以上の警告が発生していると,返却される理由コードの最初のものは次に示すコードのどれかになります。
     MQRC_MULTIPLE_REASONS
     MQRC_INCOMPLETE_MSG
     MQRC_INCOMPLETE_GROUP
     MQRC_PRIORITY_EXCEEDS_MAXIMUM
     MQRC_UNKNOWN_REPORT_OPTION