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解決したキューマネジャ名称ヌル文字列/空白
注※1
Versionフィールドの値がMQOD_VERSION_2以降の場合だけ存在するフィールドです。
注※2
Versionフィールドの値がMQOD_VERSION_3以降の場合だけ存在するフィールドです。

概要

目的

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は,次に示す構造体を持ちます。

次の値を指定できます。

MQSID_NONE
セキュリティ識別子は指定されません。
フィールドの長さ分バイナリ0の値です。
C言語では,MQSID_NONE_ARRAY定数も定義されています。MQSID_NONEと同じ値ですが,文字列ではなく,文字配列です。

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

このフィールドの長さは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
オブジェクト記述子の構造体識別子
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です。