MQGET命令 - メッセージの取り出し
機能
MQGET命令で,ローカルキューからメッセージを取り出せます。ローカルキューは,MQOPEN命令でオープンしておく必要があります。
形式
C言語の場合
MQGET(MQHCONN Hconn, MQHOBJ Hobj, PMQVOID MsgDesc,
PMQVOID GetMsgOpts, MQLONG BufferLength,
PMQVOID Buffer, PMQLONG DataLength,
PMQLONG CompCode, PMQLONG Reason)
COBOL言語の場合
CALL 'MQGET' USING HCONN, HOBJ, MSGDESC, GETMSGOPTS,
BUFFERLENGTH, BUFFER, DATALENGTH, COMPCODE, REASON.
引数
● Hconn(MQHCONN型) -input
コネクションハンドルです。
キューマネジャへの接続を示すハンドルです。MQCONN命令の戻り値を指定してください。
● Hobj(MQHOBJ型) -input
オブジェクトハンドルです。
メッセージを取り出すキューのハンドルです。MQOPEN命令の戻り値を指定してください。そのキューは,次に示すオプションを一つ以上使用してオープンしておく必要があります。詳細については,この章の「MQOPEN命令 - オブジェクトのオープン」を参照してください。
MQOO_INPUT_SHARED
MQOO_INPUT_EXCLUSIVE
MQOO_INPUT_AS_Q_DEF
MQOO_BROWSE
● MsgDesc(MQMD構造体) -input/output
メッセージ記述子です。
この構造体で,取り出したいメッセージの属性を記述します。また,取り出したメッセージの属性が返されます。詳細については,「1. データタイプ」の「MQMD構造体 - メッセージ記述子」を参照してください。
BufferLength引数の値がメッセージ長より短い場合でも,キューマネジャによってMsgDesc引数に値が設定されます。これは,GetMsgOpts引数でMQGMO_ACCEPT_TRUNCATED_MSGを指定しても指定しなくても同様です。詳細については,「1. データタイプ」の「MQGMO構造体 - メッセージ取り出しオプション」でOptionsフィールドの説明を参照してください。
アプリケーションがバージョン1のMQMD構造体を指定すると,返却されるメッセージには,アプリケーションメッセージデータの前にMQMDE構造体が付加されます。これは,MQMDE構造体の一つ以上のフィールドが初期値以外の場合だけです。MQMDE構造体のFormatフィールドにあるMQFMT_MD_EXTENSIONのフォーマット名は,MQMDE構造体が存在することを示します。
● GetMsgOpts(MQGMO構造体) -input/output
メッセージ取り出しオプションです。
詳細については,「1. データタイプ」の「MQGMO構造体 - メッセージ取り出しオプション」を参照してください。
● BufferLength(MQLONG型) -input
メッセージデータを格納するバッファのバイト長です。
0も指定できます。0を指定した場合は,データのないメッセージを取り出すものとみなされるか,メッセージがキューから削除されて,破棄されなければなりません。メッセージを削除する場合は,MQGMO_ACCEPT_TRUNCATED_MSGの指定が必要です。
● Buffer(MQBYTE型×BufferLength) -output
メッセージデータを格納するバッファです。
バッファには,メッセージ中のデータに適したバウンダリ調整が必要です。多くのメッセージ(MQヘッダ構造体のあるメッセージを含む)には4バイト単位の調整が適していますが,より厳しい調整が必要なメッセージもあります。例えば,64ビット2進整数を含めるメッセージには8バイト単位のバウンダリ調整が必要です。
BufferLength引数の値がメッセージ長より短い場合,Bufferの領域に格納できるだけのメッセージが返されます。これは,GetMsgOpts引数にMQGMO_ACCEPT_TRUNCATED_MSGを指定しても指定しなくても同様です。詳細については,「1. データタイプ」の「MQGMO構造体 - メッセージ取り出しオプション」でOptionsフィールドの説明を参照してください。
Bufferの領域の文字セットとマシンコード形式は,MsgDesc引数のCodedCharSetIdフィールドとEncodingフィールドに返されます。要求される値と異なる場合,アプリケーションメッセージデータを,その文字セットとマシンコード形式に変換してください。アプリケーションメッセージデータを変換するため,
MQGMO_CONVERTオプションを使用できます。詳細については,「1. データタイプ」の「MQGMO構造体 - メッセージ取り出しオプション」でOptionsフィールドの説明を参照してください。
命令が失敗した場合でも,Bufferの領域の内容が変わることがあります。
C言語では,void型のポインタとしてこの引数を宣言します。したがって,どんなデータタイプのアドレスでも引数として指定できます。
BufferLength引数に0を指定した場合,Buffer引数は参照されません。したがって,C言語のプログラムでは,この引数のアドレスとしてヌルを指定できます。
● DataLength(MQLONG型) -output
メッセージ長です。
メッセージのアプリケーションデータのバイト長です。データ長がBufferLength引数の値より大きい場合,BufferLengthのバイト数だけがBuffer引数に返されます。この場合,領域を超えたメッセージの部分は切り捨てられます。この値が0の場合,メッセージにアプリケーションデータがなかったことを意味します。
BufferLength属性の値がメッセージ長より短い場合でも,キューマネジャによってDataLength引数に実際のメッセージの長さが設定されます。これは,GetMsgOpts引数にMQGMO_ACCEPT_TRUNCATED_MSGオプションを指定しても指定しなくても同様です。詳細については,「1. データタイプ」の「MQGMO構造体 - メッセージ取り出しオプション」でOptionsフィールドの説明を参照してください。これによってアプリケーションは,メッセージ全体を格納できるバッファを確保して,再び命令を呼び出せます。
ただし,MQGMO_CONVERTオプションが指定され,変換されたメッセージデータが大き過ぎてBuffer引数に設定できない場合,DataLength引数には,キューマネジャ定義のフォーマットに対応する未変換データの長さが設定されます。
データの性質上,変換中のデータが拡大することがあるため,アプリケーションは,キューマネジャがDataLength引数に設定した値より大きいバッファを割り当ててください。
● CompCode(MQLONG型) -output
完了コードです。
次のどれかが返されます。
● Reason(MQLONG型) -output
理由コードです。
CompCode引数がMQCC_OKの場合
理由コード | 数値 | 意味 |
---|---|---|
MQRC_NONE | 0 | 理由コードはありません。 |
CompCode引数がMQCC_WARNINGの場合
理由コード | 数値 | 意味 |
---|---|---|
MQRC_CONVERTED_MSG_TOO_BIG | 2120 | 変換したメッセージがアプリケーションバッファに対して大き過ぎます。 |
MQRC_FORMAT_ERROR | 2110 | メッセージのフォーマットが不正です。 |
MQRC_INCONSISTENT_CCSIDS | 2243 | メッセージセグメントが異なるCCSIDを持っています。 |
MQRC_INCONSISTENT_ENCODINGS | 2244 | メッセージセグメントが異なるマシンコード形式を持っています。 |
MQRC_INCONSISTENT_UOW | 2245 | コミット単位の指定が矛盾しています。 |
MQRC_NO_MSG_LOCKED | 2209 | 排他状態のメッセージはありません。 |
MQRC_NOT_CONVERTED | 2119 | メッセージデータは変換されません。 |
MQRC_SOURCE_CCSID_ERROR | 2111 | 生成元コード化文字セット識別子が無効です。 |
MQRC_TARGET_CCSID_ERROR | 2115 | 受信側コード化文字セット識別子が無効です。 |
MQRC_TRUNCATED_MSG_ACCEPTED | 2079 | バッファ不足のため,メッセージの後部を切り捨てました(処理は完了しました)。 |
MQRC_TRUNCATED_MSG_FAILED | 2080 | バッファ不足のため,メッセージの後部を切り捨てました(処理は完了していません)。 |
CompCode引数がMQCC_FAILEDの場合
理由コード | 数値 | 意味 |
---|---|---|
MQRC_BUFFER_ERROR | 2004 | バッファの引数が不正です。 |
MQRC_BUFFER_LENGTH_ERROR | 2005 | バッファ長の引数が不正です。 |
MQRC_DATA_LENGTH_ERROR | 2010 | データ長の引数が不正です。 |
MQRC_GET_INHIBITED | 2016 | 指定されたキューからの取り出しが禁止されています。 |
MQRC_GMO_ERROR | 2186 | メッセージ取り出しオプションの構造体が不正です。 |
MQRC_HCONN_ERROR | 2018 | コネクションハンドルが不正です。 |
MQRC_HOBJ_ERROR | 2019 | オブジェクトハンドルが不正です。 |
MQRC_INCONSISTENT_BROWSE | 2259 | ブラウズ指定が矛盾しています。 |
MQRC_INCONSISTENT_UOW | 2245 | コミット単位の指定が矛盾しています。 |
MQRC_INVALID_MSG_UNDER_CURSOR | 2246 | メッセージ下のカーソルは取り出せません。 |
MQRC_MATCH_OPTIONS_ERROR | 2247 | 一致オプションが不正です。 |
MQRC_MD_ERROR | 2026 | メッセージ記述子が不正です。 |
MQRC_MSG_SEQ_NUMBER_ERROR | 2250 | メッセージシーケンス番号が無効です。 |
MQRC_NO_MSG_AVAILABLE | 2033 | 該当するメッセージがありません。 |
MQRC_NO_MSG_UNDER_CURSOR | 2034 | 検索カーソルの位置にメッセージがありません。 |
MQRC_NOT_OPEN_FOR_BROWSE | 2036 | キューが検索用にオープンされていません。 |
MQRC_NOT_OPEN_FOR_INPUT | 2037 | キューが取り出し用にオープンされていません。 |
MQRC_OBJECT_DAMAGED | 2101 | オブジェクトが破損しています。 |
MQRC_OPTIONS_ERROR | 2046 | オプションが不正です。または,指定されていません。 |
MQRC_Q_DELETED | 2052 | キューが削除されています。 |
MQRC_Q_MGR_STOPPING | 2162 | キューマネジャが終了処理中です。 |
MQRC_RESOURCE_PROBLEM | 2102 | システム資源が不足しています。 |
MQRC_STORAGE_NOT_AVAILABLE | 2071 | 記憶容量が不足しています。 |
MQRC_SYNCPOINT_NOT_AVAILABLE | 2072 | 同期点処理はできません。 |
MQRC_UNEXPECTED_ERROR | 2195 | 予期しないエラーが発生しました。 |
MQRC_WAIT_INTERVAL_ERROR | 2090 | MQGMO構造体の待ち合わせ最大時間が不正です。 |
MQRC_WRONG_GMO_VERSION | 2256 | MQGMO構造体で指定されたバージョンは不正です。 |
MQRC_WRONG_MD_VERSION | 2257 | MQMD構造体で指定されたバージョンは不正です。 |
詳細は,「付録B.2 理由コード」を参照してください。
注意事項