MOVE 33 TO MQ-BUFFLEN
5 MQC クライアント機能の
C++ インタフェース
この章では，MQC クライアント機能の C++ インタフェースに ついて説明します。
MQCクライアント機能のC++クラス一覧 C++クラス継承図
ImqBinaryクラス（C++）
ImqCacheクラス（C++）
ImqDeadLetterHeaderクラス（C++）
ImqDistributionListクラス（C++）
ImqErrorクラス（C++）
ImqGetMessageOptionsクラス（C++）
ImqHeaderクラス（C++）
ImqItemクラス（C++）
ImqMessageクラス（C++）
ImqMessageTrackerクラス（C++）
ImqObjectクラス（C++）
ImqProcessクラス（C++）
ImqPutMessageOptionsクラス（C++）
ImqQueueクラス（C++）
ImqQueueManagerクラス（C++）
ImqReferenceHeaderクラス（C++）
ImqStringクラス（C++）
ImqTriggerクラス（C++）
C++のサンプルアプリケーション C++のサンプルコーディング
MQC クライアント機能の C++ クラス一覧
MQCクライアント機能が提供するC++クラスの一覧を次の表に示します。
表5-1 クラスの一覧（C++）
クラス名 機能
ImqBinary 2進バイトアレイをカプセル化します。
ImqCache データのメモリ保持および整理をカプセル化しま
す。
ImqDeadLetterHeader MQDLH構造体の特定の機能をカプセル化しま
す。
ImqDistributionList 配布リストをカプセル化します。
ImqError エラーに関する情報を提供します。
ImqGetMessageOptions MQGMO構造体をカプセル化します。
ImqHeader MQDLH構造体の共通機能をカプセル化します。
ImqItem 一つのメッセージ内の一つの項目です。
ImqMessage MQMD構造体のカプセル化します。
ImqMessageTracker ImqMessageまたはImqQueueオブジェクトと
関連づけできる属性をカプセル化します。
ImqObject キューマネジャおよびキューの属性をカプセル化
します。
ImqProcess トリガモニタによってトリガできるアプリケー
ションプロセスの属性をカプセル化します。
ImqPutMessageOptions MQPMO構造体をカプセル化します。
ImqQueue キューの属性およびアクセスをカプセル化しま
す。
ImqQueueManager キューマネジャの属性およびアクセスをカプセル
化します。
ImqReferenceHeader MQRMH構造体をカプセル化します。
ImqString ヌル文字で終了する文字列に，記憶域と操作を提
供します。
ImqTrigger MQTM構造体をカプセル化します。
C++ クラス継承図
クラス継承図を次の図に示します。
図5-1 クラス継承図（C++の場合）
ImqBinary クラス（C++）
このクラスは，ImqMessageTrackerクラスのaccounting token，correlation id，およ びmessage id値に使用できる2進バイトアレイをカプセル化します。これによって，割 り当て，コピー，および比較が容易になります。
インクルードファイル
このクラスを使用するときは，imqbin.hppファイルをインクルードしてください。
オブジェクト属性
● data
2進データのバイトアレイです。初期値はヌル文字です。
● data length
バイト数です。初期値はヌルです。
● data pointer
dataの最初のバイトのアドレスです。初期値はヌルです。
コンストラクタ
● ImqBinary( );
デフォルトのコンストラクタです。
● ImqBinary(const ImqBinary & binary );
コピーコンストラクタです。
● ImqBinary( const void * data， const size_t length );
dataからlength分のバイトをコピーします。
メソッド
● virtual ImqBoolean copyOut( ImqMessage & msg );
多重定義されたImqItemメソッドです。dataをメッセージバッファにコピーし，既存 の内容があれば置き換えます。msg formatをMQFMT_NONEに設定します。
詳細については，「ImqItemクラス（C++）」の「メソッド」を参照してください。
● virtual ImqBoolean pasteIn( ImqMessage & msg );
多重定義されたImqItemメソッドです。メッセージバッファから残っているデータを転 送し，既存のdataを置き換えることによって，dataを設定します。正常に実行される
ためには，ImqMessage formatがMQFMT_NONEでなければなりません。
詳細については，「ImqItemクラス（C++）」の「メソッド」を参照してください。
● void operator = ( const ImqBinary & binary );
binary分のバイトをコピーします。
● ImqBoolean operator == ( const ImqBinary & binary );
このオブジェクトをbinaryと比較します。これらが等しくない場合は0を，それ以外の 場合は「0でない」を返します。二つのオブジェクトが同じdatalengthを持っており，
バイト数が一致する場合，二つのオブジェクトは等しいと見なされます。
● ImqBoolean copyOut( void * buffer， const size_t length， const char pad = 0 );
最大length分のバイトをdata pointerからbufferへコピーします。data lengthが不十 分であるときは，buffer内の残りのスペースにはpad分のバイトが埋められます。
lengthも0である場合は，bufferが0であると考えられます。lengthが負であってはな りません。正常に実行された場合はTRUEを返します。
● size_t dataLength( ) const ;
data lengthを返します。
● ImqBoolean setDataLength( const size_t length );
data lengthを設定します。このメソッドの結果としてdata lengthが変更された場合，
オブジェクト内のデータの初期設定は解除されます。正常に実行された場合はTRUEを 返します。
● void * dataPointer( ) const ;
data pointerを返します。
● ImqBoolean isNull( ) const ;
data lengthが0である場合，またはdataバイトがすべて0である場合はTRUEを返し ます。それ以外の場合はFALSEを返します。
● ImqBoolean set( const void * buffer， const size_t length );
bufferからlength分のバイトをコピーします。正常に実行された場合はTRUEを返し ます。
メソッド（protected）
● void clear( );
data lengthを減らして0にします。
その他の関連クラス
ImqItem ImqMessage
理由コード
• MQRC_NO_BUFFER
• MQRC_STORAGE_NOT_AVAILABLE
理由コードの詳細については，「付録A 理由コード」，またはマニュアル「TP1/
Message Queue プログラム作成リファレンス」を参照してください。
ImqCache クラス（C++）
このクラスは，データをメモリに保持したり，整理したりするのに使用します。ユーザ が固定サイズのメモリのバッファを指定したり，システムによる自動的で柔軟なメモリ 設定に任せたりもできます。
インクルードファイル
このクラスを使用するときは，imqcac.hppファイルをインクルードしてください。
オブジェクト属性
● automatic buffer
バッファメモリがシステムによって自動的に管理されるときはTRUE，ユーザによって 提供されるときはFALSEを示します。初期値はTRUEです。
● buffer length
バッファ内のメモリのバイト数です。初期値は0です。
● buffer pointer
バッファメモリのアドレスです。初期値はヌルです。
● data length
data pointerよりあとのバイト数です。message lengthに等しいか，それより小さい数 値です。初期値は0です。
● data offset
data pointerより前のバイト数です。message lengthに等しいか，それより小さい数値 です。初期値は0です。
● data pointer
読み取りまたは書き込みが実行されるバッファのアドレスです。初期値はヌルです。
● message length
バッファ内の有効なデータのバイト数です。初期値は0です。
コンストラクタ
● ImqCache( );
デフォルトのコンストラクタです。
● ImqCache( const ImqCache & cache );
コピーコンストラクタです。
メソッド
● void operator = ( const ImqCache & cache );
message length分のバイトのデータをcacheオブジェクトから該当するオブジェクトへ コピーします。automatic bufferがFALSEである場合は，buffer lengthが，コピーさ れたデータを収容できるだけの大きさでなければなりません。
● ImqBoolean automaticBuffer( ) const ;
automatic bufferの値を返します。
● size_t bufferLength( ) const ;
buffer lengthを返します。
● char * bufferPointer( ) const ;
buffer pointerを返します。
● void clearMessage( );
message lengthとdata offsetを両方とも0に設定します。
● size_t dataLength( ) const ;
data lengthを返します。
● size_t dataOffset( ) const ;
data offsetを返します。
● ImqBoolean setDataOffset( const size_t offset );
data offsetを設定します。message lengthがdata offset以上であることが必要なとき は，message lengthを増やします。正常に実行された場合はTRUEを返します。
● char * dataPointer( ) const ;
data pointerのコピーを返します。
● size_t messageLength( ) const ;
message lengthを返します。
● ImqBoolean setMessageLength( const size_t length );
message lengthを設定します。
message lengthがbuffer length以下であることが必要なときは，buffer lengthを増や します。data offsetがmessage length以下であることが必要なときは，data offsetを減 らします。正常に実行された場合はTRUEを返します。
● ImqBoolean moreBytes( const size_t bytes-required );
data pointerからバッファの終わりまでの間で，さらにbytes-required分のバイトを書 き込みに使用できるようにします。正常に実行された場合はTRUEを返します。
automatic bufferがTRUEである場合は，必要に応じて，さらに多くのメモリが取得さ れます。それ以外の場合は，buffer lengthが十分な大きさでなければなりません。
● ImqBoolean read( const size_t length， char * & external-buffer );
length分のバイトを，data pointer位置で始まるバッファからexternal-bufferへコピー します。データがコピーされたあとで，data offsetはlengthだけ増やされます。正常に 実行された場合はTRUEを返します。
● ImqBoolean resizeBuffer( const size_t length );
automatic bufferがTRUEである場合は，バッファメモリを再度割り振ることによって，
buffer lengthを変更します。
既存のバッファから最大message length分のバイトのデータが新しいバッファにコピー されます。コピーされる最大数はlengthバイトです。buffer pointerは変更されます。
message lengthとdata offsetは，新しいバッファの範囲内で可能な限り接近して予約さ れます。正常に実行された場合はTRUEを返します。automatic bufferがFALSEであ る場合はFALSEを返します。
注意
システム資源に問題があると，このメソッドは失敗し，理由コード MQRC_STORAGE_NOT_AVAILABLEが返されます。
● ImqBoolean useEmptyBuffer( const char * external-buffer， const size_t length );
空のユーザバッファを識別し，buffer pointerがexternal-bufferを示すように設定し，
buffer lengthをlengthに，また，message lengthを0にそれぞれ設定します。
clearMessageを実行します。バッファがデータで完全に満たされている場合は，代わり にuseFullBufferメソッドを使用してください。バッファの一部にデータが入っている 場合は，setMessageLengthメソッドを使用して，正しい量を示してください。正常に 実行された場合はTRUEを返します。
このように，このメソッドを使用して，固定量のメモリ（external-bufferがヌル文字で なく，lengthが0でない）を識別できます。この場合，automatic bufferはFALSEに 設定されます。また，システムによる柔軟なメモリ管理（external-bufferがヌル文字で，
かつlengthが0である）に戻すこともできます。この場合，automatic bufferはTRUE
に設定されます。
● ImqBoolean useFullBuffer( const char * externalBuffer， const size_t length );
このメソッドとImqBoolean useEmptyBufferメソッドの違いは，message lengthが lengthに設定されていることだけです。正常に実行された場合はTRUEを返します。
● ImqBoolean write( const size_t length， const char * external-buffer );
length分のバイトを，external-bufferから，data1 pointer位置で始まるバッファへコ ピーします。データがコピーされたあとで，data offsetはlengthだけ増やされます。ま た，message lengthが新しいdata offset値以上になるようにする必要がある場合は message lengthが増やされます。正常に実行された場合はTRUEを返します。
automatic bufferがTRUEである場合は，十分な量のメモリが保証されます。それ以外 の場合は，最終的なdata offsetがbuffer lengthを超えてはいけません。
その他の関連クラス
ImqError
理由コード
• MQRC_BUFFER_NOT_AUTOMATIC
• MQRC_DATA_TRUNCATED
• MQRC_INSUFFICIENT_BUFFER
• MQRC_INSUFFICIENT_DATA
• MQRC_NULL_POINTER
• MQRC_STORAGE_NOT_AVAILABLE
• MQRC_ZERO_LENGTH
理由コードの詳細については，「付録A 理由コード」，またはマニュアル「TP1/
Message Queue プログラム作成リファレンス」を参照してください。