MQOD構造体　−　オブジェクト記述子

目的

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は次の場合にだけ使用されます。

• MQOO_ALTERNATE_USER_AUTHORITYがMQOPEN命令に指定されるか，MQOO_ALTERNATE_USER_AUTHORITYがMQPUT1命令に指定される場合

• AlternateUserIdフィールドの最初のヌル文字まで，またはフィールドの最後までのすべてが空白ではない場合

AlternateSecurityIdは，次に示す構造体を持ちます。

• 先頭バイトは後続データの長さを含むバイナリ整数値であり，その長さは，長さを示すバイト自身も含みます。セキュリティ識別子がない場合，長さは0です。

• 2番目のバイトはセキュリティ識別子のタイプを示し，次の値を取ることができます。

  • MQSIDT_NT_SECURITY_ID：Windowsセキュリティ識別子

  • MQSIDT_NONE：セキュリティ識別子ではありません。

• 3番目以降のバイトから，先頭バイトで定義された長さまでのバイトはセキュリティ識別子自身です。

• 残りのバイトはバイナリ0に設定されます。

次の値を指定できます。

MQSID_NONE

セキュリティ識別子は指定されません。

フィールドの長さ分バイナリ0の値です。

C言語では，MQSID_NONE_ARRAY定数も定義されています。MQSID_NONEと同じ値ですが，文字列ではなく，文字配列です。

これは入力用のフィールドです。

このフィールドの長さはMQ_SECURITY_ID_LENGTHです。

このフィールドの初期値はMQSID_NONEです。

このフィールドは，Versionフィールドの値がMQOD_VERSION_3以降の場合だけ有効です。

TP1/Message Queueではこのフィールドは意味を持ちません。

●　AlternateUserId（MQCHAR12型）　代替ユーザ識別子

次のどちらかの場合，このフィールドに代替ユーザ識別子を指定します。

• MQOPEN命令でMQOO_ALTERNATE_USER_AUTHORITYを指定した場合

• MQPUT1命令でMQPMO_ALTERNATE_USER_AUTHORITYを指定した場合

キューに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のキューマネジャに定義されたオブジェクトのローカル名です。

この名前には，次に示す文字を使用できます。

• 英大文字（A〜Z）

• 英小文字（a〜z）

• 数字（0〜9）

• ピリオド（.），スラント（/），アンダスコア（_），パーセント（%）

名前の先頭および中間には，空白を使用できません。末尾には空白を使用できます。名前の中で有効なデータの末尾を示すためにヌル文字を使用できます。ヌル文字とそれに続く文字はすべて空白として処理されます。

次に示す点は，該当するオブジェクトタイプに適用されます。

• ObjectNameフィールドがモデルキューの名前である場合，キューマネジャは，モデルキューの属性で動的キューを生成し，生成されたキューの名前をObjectNameフィールドに返します。モデルキューはMQOPEN命令にだけ指定できます。MQPUT1命令では無効です。

• オープンされているオブジェクトが配布リストの場合（つまり，RecsPresentフィールドがあり，ゼロより大きい場合），ObjectNameフィールドは空白またはヌル文字列にする必要があります。条件が満たされない場合，命令は失敗し，理由コードMQRC_OBJECT_NAME_ERRORが返されます。

• ObjectTypeフィールドにMQOT_Q_MGRを指定したときは，最初のヌル文字までまたはフィールドの最後までを，空白で埋める必要があります。

このフィールドは，MQOPEN命令でモデルキュー名を指定した場合は，入出力用のフィールドとなります。そのほかの場合は，入力専用のフィールドです。

このフィールドの長さは，MQ_Q_NAME_LENGTHに定義されています。

このフィールドの初期値は，C言語ではヌル文字列です。そのほかのプログラミング言語では，48個の空白です。

●　ObjectQMgrName（MQCHAR48型）　オブジェクトキューマネジャ名

ObjectNameのオブジェクトを定義している，キューマネジャの名称です。

この名前で有効な文字は，ObjectNameフィールドと同じです。最初のヌル文字またはフィールドの最後まで，全体が空白である名前は，アプリケーションが接続されるキューマネジャ（ローカルキューマネジャ）を表します。

次に示す項目は，該当するオブジェクトタイプに適用されます。

• ObjectTypeフィールドがMQOT_PROCESSまたはMQOT_Q_MGRである場合は，ObjectQMgrNameフィールドは空白，またはローカルキューマネジャの名前にする必要があります。

• ObjectNameフィールドにモデルキュー名を指定したときは，キューマネジャによってモデルキューの属性でキューが生成されます。このとき，生成されたキューを定義しているキューマネジャの名称がObjectQMgrNameフィールドに返されます。モデルキューは，MQOPEN命令のときだけ指定できます。MQPUT1命令では無効です。

• ObjectNameがクラスタキューの名称で，かつObjectQMgrNameが空白の場合，MQOPEN命令で返却されたキューハンドルを使用して送信されたメッセージの実際のあて先はキューマネジャによって選択されます。

  • MQOO_BIND_ON_OPENが指定された場合，キューマネジャはMQOPEN命令の処理でクラスタキューの中にある特定のキューを選択し，そのキューハンドルを使用して登録したすべてのメッセージはそのキューに送信されます。

  • MQOO_BIND_NOT_FIXEDが指定された場合，そのキューハンドルを使用した後続のMQPUT命令では，クラスタ内の異なるキューマネジャ上に存在するあて先キューの中の異なるキューが選択される場合もあります。

  アプリケーションが特定のクラスタキュー，つまり，クラスタ内の特定のキューマネジャ上に存在するキューにメッセージを送信する必要がある場合，アプリケーションはObjectQMgrNameフィールドに，そのキューマネジャ名称を指定する必要があります。これによって，ローカルキューマネジャは指定されたあて先キューマネジャにメッセージを送信します。

• 配布リストがオープンされている場合，つまり，RecsPresentが存在し，かつ0より大きい場合は，ObjectNameは空白かヌル文字列でなければなりません。それ以外では，理由コードMQRC_OBJECT_Q_MGR_NAME_ERRORで失敗します。

このフィールドは，MQOPEN命令でモデルキュー名を指定した場合は，入出力用のフィールドとなります。そのほかの場合は，入力専用のフィールドです。

ObjectQMgrNameフィールドの長さは，MQ_Q_MGR_NAME_LENGTHに定義されています。

このフィールドの初期値は，C言語ではヌル文字列です。そのほかのプログラミング言語では，48個の空白です。

●　ObjectRecOffset（MQLONG型）　最初のオブジェクトレコードまでのオフセット

MQOD構造体の先頭から最初のMQOR構造体のオブジェクトレコードのバイトオフセットです。

オフセットの値は正の場合も負の場合もあります。ObjectRecOffsetフィールドは，配布リストがオープンされているときだけ使用されます。RecsPresentフィールドが0であれば，無視されます。

配布リストがオープンされているとき，一つ以上のMQOR構造体のオブジェクトレコードの配列が配布リストのあて先キューの名称を指定するために指定されなければなりません。次に示すどちらかの方法で指定してください。

• ObjectRecOffsetフィールドを使用して指定する方法

  アプリケーションは，必要な要素のあるMQOR構造体のレコード配列が続くMQOD構造体を含む構造体を宣言しなければなりません。また，ObjectRecOffsetフィールドをMQOD構造体の開始からその配列の最初の要素までのオフセットに指定しなければなりません。このオフセットが正しく，値がMQLONGに収まることを確認してください（最も制限の強いプログラミング言語はCOBOL言語です。有効範囲は-999999999〜+999999999です）。

  ObjectRecOffsetフィールドは，ポインタのデータ型をサポートしていない，または異なる環境に移植しない場合にポインタ型のデータ型を実装するプログラム言語（例：COBOL言語）でプログラミングするときに使用することをお勧めします。

• ObjectRecPtrフィールドを使用する方法

  アプリケーションは，MQOR構造体をMQOD構造体とは別に宣言できます。その後，ObjectRecPtrフィールドを配列のアドレスに設定します。

  ObjectRecPtrフィールドは，異なる環境に移植する場合にポインタのデータ型を実装するプログラム言語（例：C言語）でプログラミングするときに使用することをお勧めします。

どちらの場合も，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フィールドは空白に設定されます。

• キューではない場合

• キューであるが，オープンの目的が検索，入力および出力のどれでもない場合

• MQOO_BIND_NOT_FIXEDが指定されたクラスタキュー（または，キューのDefBind属性がMQBND_BIND_NOT_FIXEDのときのMQOO_BIND_AS_Q_DEF）

• 配布リストである場合

これは出力用のフィールドです。

このフィールドの長さは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

オブジェクト記述子の構造体識別子

C言語では，MQOD_STRUC_ID_ARRAYも定義されています。これは，MQOD_STRUC_IDと同じ値です。ただし，文字列ではなく文字の配列として定義されています。

これは入力用のフィールドです。

このフィールドの初期値はMQOD_STRUC_IDです。

●　UnknownDestCount（MQLONG型）　リモートキューの数

配布リストの中で，リモートキューで受信され，オープンに成功したキューの数です。このフィールドは，配布リストには存在しない単一のキューをオープンしたときにも設定されます。

これは出力用のフィールドです。

このフィールドの初期値は0です。

このフィールドは，Versionフィールドの値がMQOD_VERSION_2以降の場合だけ有効です。

●　Version（MQLONG型）　構造体バージョン番号

次の値を取ります。

MQOD_VERSION_1

バージョン1のオブジェクト記述子の構造体バージョン番号

MQOD_VERSION_2

バージョン2のオブジェクト記述子の構造体バージョン番号

MQOD_VERSION_3

バージョン3のオブジェクト記述子の構造体バージョン番号

MQOD_VERSION_2以降の構造体にだけ存在するフィールドについては，そのことがフィールドの説明に記載されています。次に示す定数は，現在のバージョン番号を指定します。

MQOD_CURRENT_VERSION

現在のバージョンのオブジェクト記述子の構造体バージョン番号

これは入力用のフィールドです。

このフィールドの初期値はMQOD_VERSION_1です。