MQOD構造体 - オブジェクト記述子
MQOD構造体は,次のフィールドから構成されます。
フィールド(データタイプ) | 内容 | 初期値 |
---|---|---|
StrucId(MQCHAR4型) | 構造体識別子 | MQOD_STRUC_ID |
Version(MQLONG型) | 構造体バージョン番号 | MQOD_VERSION_1 |
ObjectType(MQLONG型) | オブジェクトタイプ | MQOT_Q |
ObjectName(MQCHAR48型) | オブジェクト名 | ヌル文字列/空白 |
ObjectQMgrName(MQCHAR48型) | オブジェクトキューマネジャ名 | ヌル文字列/空白 |
DynamicQName(MQCHAR48型) | 動的キュー名 | アスタリスク(*) |
AlternateUserId(MQCHAR12型) | 代替ユーザ識別子 | ヌル文字列/空白 |
RecsPresent(MQLONG型)※1 | オブジェクトレコード数 | 0 |
KnownDestCount(MQLONG型)※1 | ローカルキューの数 | 0 |
UnknownDestCount(MQLONG型)※1 | リモートキューの数 | 0 |
InvalidDestCount(MQLONG型)※1 | オープンに失敗したキューの数 | 0 |
ObjectRecOffset(MQLONG型)※1 | 最初のオブジェクトレコードまでのオフセット | 0 |
ResponseRecOffset(MQLONG型)※1 | 最初の応答レコードまでのオフセット | 0 |
ObjectRecPtr(MQPTR型)※1 | 最初のオブジェクトレコードのアドレス | ヌルポインタ/ヌル文字列 |
ResponseRecPtr(MQPTR型)※1 | 最初の応答レコードのアドレス | ヌルポインタ/ヌル文字列 |
AlternateSecurityId(MQBYTE40型)※2 | 代替セキュリティ識別子 | MQSID_NONE |
ResolvedQName(MQCHAR48型)※2 | 解決したキュー名称 | ヌル文字列/空白 |
ResolvedQMgrName(MQCHAR48型)※2 | 解決したキューマネジャ名称 | ヌル文字列/空白 |
概要
目的
MQOD構造体は,オブジェクトを名前で指定するために使用します。記述できるオブジェクトの種類を次に示します。
この構造体は,MQOPEN命令およびMQPUT1命令の入出力用の引数です。
バージョン
MQOD構造体のバージョンには1,2および3があります。しかし,すべての環境でMQOD_VERSION_3がサポートされているわけではありません。複数の環境にアプリケーションを移植する場合は,使用するバージョンのMQOD構造体が,すべての環境でサポートされている必要があります。MQOD_VERSION_2以降の構造体にだけ存在するフィールドについては,そのことをフィールドの説明に記載しています。
サポートするプログラミング言語のCOPYファイルとINCLUDEファイルでは,最新バージョンのMQOD構造体が提供されます。ただし,Versionフィールドの初期値はMQOD_VERSION_1です。バージョン1の構造体にないフィールドを使用する場合は,アプリケーションで使用したいバージョンの番号をVersionフィールドに設定してください。
配布リストをオープンするには,Versionフィールドの値がMQOD_VERSION_2以降でなければなりません。
文字セットおよびマシンコード
MQOD構造体のデータは,ローカルキューマネジャの文字セットおよびマシンコードに従います。それぞれ,キューマネジャのCodedCharSetId属性およびMQENC_NATIVEで指定します。TP1/Message Queue - Accessのクライアントアプリケーションの場合,MQOD構造体はクライアントの文字セットとマシンコードに従います。
フィールド
構造体を構成するフィールドについて,アルファベット順に説明します。
● AlternateSecurityId(MQBYTE40型) 代替セキュリティ識別子
妥当な権限があるかどうかをチェックするために,AlternateUserIdと一緒に認証サービスに渡されるセキュリティ識別子です。
AlternateSecurityIdは次の場合にだけ使用されます。
AlternateSecurityIdは,次に示す構造体を持ちます。
次の値を指定できます。
これは入力用のフィールドです。
このフィールドの長さはMQ_SECURITY_ID_LENGTHです。
このフィールドの初期値はMQSID_NONEです。
このフィールドは,Versionフィールドの値がMQOD_VERSION_3以降の場合だけ有効です。
TP1/Message Queueではこのフィールドは意味を持ちません。
● AlternateUserId(MQCHAR12型) 代替ユーザ識別子
次のどちらかの場合,このフィールドに代替ユーザ識別子を指定します。
キューにAlternateUserIdが指定されている場合,キューマネジャは,メッセージが書き込まれるときにAlternateUserIdの値を使用します。MQPUT命令またはMQPUT1命令の呼び出しで指定されたMQPMO_*_CONTEXTオプションに従って識別コンテキスト情報を生成する場合,キューマネジャは,メッセージのMQMD構造体のUserIdentifierフィールドにAlternateUserIdの値を設定します。
代替ユーザ識別子は,実行中のアプリケーションのユーザ識別子の代わりとして使用されます。
MQOO_ALTERNATE_USER_AUTHORITYもMQPMO_ALTERNATE_USER_AUTHORITYも指定しなかった場合,このフィールドは無視されます。
これは入力用のフィールドです。
このフィールドの長さは,MQ_USER_ID_LENGTHに定義されています。
このフィールドの初期値は,C言語ではヌル文字列です。そのほかのプログラミング言語では,12個の空白です。
● DynamicQName(MQCHAR48型) 動的キュー名
MQOPEN命令によって作成される動的キューの名前です。ObjectNameフィールドにモデルキューの名前が指定された場合だけに関係します。その他の場合,DynamicQNameフィールドは無視されます。
この名前で有効な文字はObjectNameフィールドと同じです。さらに,アスタリスクも有効です。ObjectNameフィールドがモデルキューの名前である場合は,すべて空白の名前(または最初のヌル文字の前が空白だけの名前)は無効です。
空白を除く名称の最後の文字がアスタリスク(*)の場合,キューマネジャは,アスタリスクをユニークな文字列に置き換えます。これによって,ローカルキューマネジャ内でユニークなキュー名が保証されます。この方法で十分な個数の名称を確保するために,アスタリスクの位置は1文字目から33文字目の間にしてください。アスタリスクのあとには,空白・ヌル文字以外の文字を指定できません。
アスタリスクを先頭に指定してもかまいません。この場合,名称のすべての文字がキューマネジャによって生成されます。ObjectNameフィールドにモデルキュー名を指定した場合,すべて空白の名称,または最初のヌル文字まで空白の名称は不正となります。
このフィールドの長さは,MQ_Q_NAME_LENGTHに定義されています。
これは,入力用のフィールドです。このフィールドの初期値は環境に依存します。TP1/Message Queueの場合の初期値は,C言語では,ヌル文字で終わる1文字のアスタリスクです。そのほかのプログラミング言語では,余りを空白で埋められた1文字のアスタリスクです。
● InvalidDestCount(MQLONG型) オープンに失敗したキューの数
配布リストの中で,オープンに失敗したキューの数です。このフィールドは,配布リストに存在しない単一のキューをオープンしたときにも設定されます。
InvalidDestCountフィールドは,MQOPEN命令またはMQPUT1命令のCompCode引数がMQCC_OKまたはMQCC_WARNINGのときだけ設定されます。CompCode引数がMQCC_FAILEDのときには設定されません。
これは出力用のフィールドです。
このフィールドの初期値は0です。
このフィールドは,Versionフィールドの値がMQOD_VERSION_2以降の場合だけ有効です。
● KnownDestCount(MQLONG型) ローカルキューの数
配布リストの中で,ローカルキューで受信され,オープンに成功したキューの数です。最初のメッセージ登録に使用される場合も,この値はリモートキューで受信されるキューを含みません。このフィールドは,配布リストには存在しない単一のキューをオープンしたときにも設定されます。
これは出力用のフィールドです。
このフィールドの初期値は0です。
このフィールドは,Versionフィールドの値がMQOD_VERSION_2以降の場合だけ有効です。
● ObjectName(MQCHAR48型) オブジェクト名
ObjectQMgrNameのキューマネジャに定義されたオブジェクトのローカル名です。
この名前には,次に示す文字を使用できます。
名前の先頭および中間には,空白を使用できません。末尾には空白を使用できます。名前の中で有効なデータの末尾を示すためにヌル文字を使用できます。ヌル文字とそれに続く文字はすべて空白として処理されます。
次に示す点は,該当するオブジェクトタイプに適用されます。
このフィールドは,MQOPEN命令でモデルキュー名を指定した場合は,入出力用のフィールドとなります。そのほかの場合は,入力専用のフィールドです。
このフィールドの長さは,MQ_Q_NAME_LENGTHに定義されています。
このフィールドの初期値は,C言語ではヌル文字列です。そのほかのプログラミング言語では,48個の空白です。
● ObjectQMgrName(MQCHAR48型) オブジェクトキューマネジャ名
ObjectNameのオブジェクトを定義している,キューマネジャの名称です。
この名前で有効な文字は,ObjectNameフィールドと同じです。最初のヌル文字またはフィールドの最後まで,全体が空白である名前は,アプリケーションが接続されるキューマネジャ(ローカルキューマネジャ)を表します。
次に示す項目は,該当するオブジェクトタイプに適用されます。
このフィールドは,MQOPEN命令でモデルキュー名を指定した場合は,入出力用のフィールドとなります。そのほかの場合は,入力専用のフィールドです。
ObjectQMgrNameフィールドの長さは,MQ_Q_MGR_NAME_LENGTHに定義されています。
このフィールドの初期値は,C言語ではヌル文字列です。そのほかのプログラミング言語では,48個の空白です。
● ObjectRecOffset(MQLONG型) 最初のオブジェクトレコードまでのオフセット
MQOD構造体の先頭から最初のMQOR構造体のオブジェクトレコードのバイトオフセットです。
オフセットの値は正の場合も負の場合もあります。ObjectRecOffsetフィールドは,配布リストがオープンされているときだけ使用されます。RecsPresentフィールドが0であれば,無視されます。
配布リストがオープンされているとき,一つ以上のMQOR構造体のオブジェクトレコードの配列が配布リストのあて先キューの名称を指定するために指定されなければなりません。次に示すどちらかの方法で指定してください。
どちらの場合も,ObjectRecOffsetフィールドまたはObjectRecPtrフィールドのどちらか一つを使用しなければなりません。両方のフィールドが0,または両方のフィールドとも0以外の場合,MQRC_OBJECT_RECORDS_ERRORの理由コードで失敗します。
これは入力用のフィールドです。
このフィールドの初期値は0です。
このフィールドは,Versionフィールドの値がMQGMO_VERSION_2以降の場合だけ有効です。
● ObjectRecPtr(MQPTR型) 最初のオブジェクトレコードのアドレス
最初のオブジェクトレコードのアドレスです。ObjectRecPtrフィールドは配布リストがオープンされたときだけ使用されます。RecsPresentフィールドが0の場合は無視されます。
ObjectRecPtrフィールドまたはObjectRecOffsetフィールドのどちらかをオブジェクトレコードに指定するのに使用できます。指定方法については,「ObjectRecOffsetフィールド」を参照してください。ObjectRecPtrフィールドを使用しない場合は,ヌルポインタかヌル文字列を設定しなければなりません。
これは入力用のフィールドです。
このフィールドの初期値は,ポインタをサポートしているプログラミング言語ではヌルポインタです。文字列の場合はヌル文字列となります。
このフィールドは,Versionフィールドの値がMQGMO_VERSION_2以降の場合だけ有効です。
● ObjectType(MQLONG型) オブジェクトタイプ
ObjectNameの名称を持つオブジェクトの種類です。次の値を指定できます。
MQOT_Q:キュー
MQOT_PROCESS:プロセス定義
MQOT_Q_MGR:キューマネジャ
これは入力用のフィールドです。
このフィールドの初期値はMQOT_Qです。
● RecsPresent(MQLONG型) オブジェクトレコード数
アプリケーションによって指定されたMQOR構造体のオブジェクトレコードの数です。この数が0より大きい場合,配布リストが,そのリスト中のあて先キューと同じ数だけ存在するRecsPresentフィールドに対してオープンされていることを示しています。ただし,配布リストがただ一つのあて先だけを含んでいる場合もあります。
RecsPresentフィールドの値は0より大きくなければなりません。また,その場合,ObjectTypeフィールドはMQOT_Qでなければなりません。この条件が満たされない場合,MQRC_RECS_PRESENT_ERRORの理由コードで失敗します。
これは入力用のフィールドです。
このフィールドの初期値は0です。
このフィールドは,Versionフィールドの値がMQGMO_VERSION_2以降の場合だけ有効です。
● ResolvedQMgrName(MQCHAR48型) 解決したキューマネジャ名称
ローカルキューマネジャに定義される最終のあて先キューマネジャの名称です。
ローカルキューマネジャが名称解決を実行したあとのあて先キューマネジャの名前です。返される名前は,ResolvedQNameフィールドに指定されたキューを保持するキューマネジャの名前です。ResolvedQMgrNameフィールドは,ローカルキューマネジャの名前になることがあります。
空白でない値が返されるのは,オブジェクトが検索,入力または出力(またはこれらの組み合わせ)を目的にオープンされた単一のキューである場合だけです。オープンされているオブジェクトが次に示すどれかである場合,ResolvedQMgrNameフィールドは空白に設定されます。
これは出力用のフィールドです。
このフィールドの長さはMQ_Q_NAME_LENGTHです。
このフィールドの初期値は,C言語ではヌル文字列です。そのほかのプログラミング言語では,48個の空白です。
このフィールドは,Versionフィールドの値がMQOD_VERSION_3以降の場合だけ有効です。
● ResolvedQName(MQCHAR48型) 解決したキュー名称
ローカルキューマネジャに知らされる最終のあて先キューの名称です。
ローカルキューマネジャが名称解決を実行したあとのあて先キューの名前です。返される名前は,ResolvedQMgrNameフィールドに指定されたキューマネジャが保持するキューの名前です。
空白でない値が返されるのは,オブジェクトが検索,入力または出力(またはこれらの組み合わせ)を目的にオープンされた単一のキューである場合だけです。オープンされているオブジェクトが次に示すどれかである場合,ResolvedQNameフィールドは空白に設定されます。
これは出力用のフィールドです。
このフィールドの長さはMQ_Q_NAME_LENGTHです。
このフィールドの初期値は,C言語ではヌル文字列です。そのほかのプログラミング言語では,48個の空白です。
このフィールドは,Versionフィールドの値がMQOD_VERSION_3以降の場合だけ有効です。
● ResponseRecOffset(MQLONG型) 最初の応答レコードまでのオフセット
MQOD構造体の先頭から最初のMQRR構造体の応答レコードまでのバイトオフセットです。オフセットは正の場合も負の場合もあります。ResponseRecOffsetフィールドは,配布リストがオープンされているときだけ使用できます。RecsPresentフィールドが0の場合は無視されます。
配布リストがオープンされているとき,一つ以上のMQRR構造体の応答レコードの配列がオープンに失敗したキューと,その失敗の理由を特定するために指定されなければなりません。なお,オープンに失敗したキューはMQRR構造体のCompCodeフィールドに記述され,その失敗の理由はMQRR構造体のReasonフィールドに記述されます。
データは,キュー名称がオブジェクトレコードの配列に現れるのと同じ順序で応答レコードの配列に返されます。キューマネジャが応答レコードを設定するのは,命令の結果が混在しているときだけです。例えば,次のような場合です。
この場合,MQRC_MULTIPLE_REASONSの理由コードが出現します。同じ理由コードがすべてのキューに適用される場合,応答レコードは設定されません。応答レコードは任意で指定できます。ただし,指定する場合は,RecsPresentフィールドと同じ数だけ指定しなければなりません。
応答レコードはオブジェクトレコードと同じように,ResponseRecOffsetフィールドのオフセットまたはResponseRecPtrのアドレスを指定できます。指定方法については,「ObjectRecOffsetフィールド」を参照してください。ただし,ResponseRecOffsetフィールドとResponseRecPtrフィールドは一つ以上指定できません。どちらのフィールドも0以外の場合は,MQRC_RESPONSE_RECORDS_ERRORの理由コードで失敗します。
キューをオープンしたときのエラーと同様に,応答レコードは,MQPUT1命令でメッセージが配布リストのキューに送信されるときに発生したエラーに関する情報を返すのに使用されます。キューに対するオープン処理の完了コードがMQCC_OKまたはMQCC_WARNINGの場合だけ,キューに対する登録操作の完了コードと理由コードに置き換えます。
これは入力用のフィールドです。
このフィールドの初期値は0です。
このフィールドは,Versionフィールドの値がMQOD_VERSION_2以降の場合だけ有効です。
● ResponseRecPtr(MQPTR型) 最初の応答レコードのアドレス
最初の応答レコードのアドレスです。このフィールドは,配布リストがオープンされたときだけ使用されます。RecsPresentフィールドが0の場合は無視されます。
応答レコードの指定には,ResponseRecPtrフィールドまたはResponseRecOffsetフィールドを同時に使用できません。詳細については,「ResponseRecOffsetフィールド」を参照してください。
ResponseRecPtrフィールドが使用されない場合,ヌルポインタかヌル文字列を設定しなければなりません。
これは入力用のフィールドです。
このフィールドの初期値は,ポインタをサポートしているプログラミング言語ではヌルポインタです。文字列の場合はヌル文字列です。
このフィールドは,Versionフィールドの値がMQOD_VERSION_2以降の場合だけ有効です。
● StrucId(MQCHAR4型) 構造体識別子
次の値を取ります。
これは入力用のフィールドです。
このフィールドの初期値はMQOD_STRUC_IDです。
● UnknownDestCount(MQLONG型) リモートキューの数
配布リストの中で,リモートキューで受信され,オープンに成功したキューの数です。このフィールドは,配布リストには存在しない単一のキューをオープンしたときにも設定されます。
これは出力用のフィールドです。
このフィールドの初期値は0です。
このフィールドは,Versionフィールドの値がMQOD_VERSION_2以降の場合だけ有効です。
● Version(MQLONG型) 構造体バージョン番号
次の値を取ります。
MQOD_VERSION_2以降の構造体にだけ存在するフィールドについては,そのことがフィールドの説明に記載されています。次に示す定数は,現在のバージョン番号を指定します。
これは入力用のフィールドです。
このフィールドの初期値はMQOD_VERSION_1です。