OpenTP1 メッセージキューイング機能　TP1/Message Queue プログラム作成リファレンス

[目次][索引][前へ][次へ]

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_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　理由コード」を参照してください。

注意事項

  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

[目次][前へ][次へ]

[他社商品名称に関する表示]

All Rights Reserved. Copyright (C) 2006, 2011, Hitachi, Ltd.
(C) Copyright International Business Machines Corporation 1994, 2003. All rights reserved.