MQMD - メッセージ記述子

MQMD 構造体には、メッセージが送信側アプリケーションと受信側アプリケーションの間を移動するときに、アプリケーション・データに付随する制御情報が含まれます。この構造体は、MQGET、MQPUT、および MQPUT1 呼び出しに指定する入出力パラメーターです。

可用性

すべての IBM® MQ システム、およびこれらのシステムに接続された IBM MQ MQI clients 。

バージョン

MQMD の現行バージョンは MQMD_VERSION_2です。複数の環境間で移植可能にすることを意図したアプリケーションでは、必ず対象のすべての環境で、必要なバージョンの MQMD がサポートされているようにしてください。これより新しいバージョンの構造体にのみ存在するフィールドについては、そのフィールドの説明にその旨を記載しています。

サポートされるプログラム言語用に提供されているヘッダー・ファイル、コピー・ファイル、およびインクルード・ファイルには、環境でサポートされる最新バージョンの MQMD が含まれていますが、Version フィールドの初期値は MQMD_VERSION_1 に設定されています。 version-1 構造体に存在しないフィールドを使用するには、アプリケーションで、Versionフィールドを必要なバージョンのバージョン番号に設定する必要があります。

バージョン 1 の構造体の宣言は、MQMD1 という名前で使用できます。

文字セットとエンコード

MQMD 内のデータは、ローカル・キュー・マネージャーの文字セットおよびエンコードでなければなりません。これらは、 CodedCharSetId キュー・マネージャー属性および MQENC_NATIVE で指定されます。ただし、アプリケーションが IBM MQ MQI clientとして実行されている場合、構造体はクライアントの文字セットとエンコードになっている必要があります。

送信側と受信側のキュー・マネージャーで使用する文字セットまたはエンコードが違う場合、MQMD のデータは自動的に変換されます。アプリケーションで MQMD を変換する必要はありません。

MQMD の異なるバージョンの使用

version-2 の MQMD は、 version-1 の MQMD を使用し、メッセージ・データの前に MQMDE 構造体を付けるのと同等です。ただし、MQMDE 構造体のすべてのフィールドにデフォルト値を設定する場合には、MQMDE を省略することができます。バージョン 1 の MQMD、および MQMDE は、次のようにして使用します。

MQPUT 呼び出しおよび MQPUT1 呼び出しでアプリケーションからバージョン 1 の MQMD を提供する場合には、オプションとして、メッセージ・データの先頭に MQMDE を付けることができます。その場合は、MQMD の Format フィールドに MQFMT_MD_EXTENSION を設定して、MQMDE が存在することを指定します。アプリケーションが MQMDE を提供しない場合、キュー・マネージャーは MQMDE の各フィールドにデフォルト値が設定されたものと見なします。
注: version-2 MQMD には存在するが、 version-1 MQMD には存在しないいくつかのフィールドは、MQPUT 呼び出しおよび MQPUT1 呼び出しの入出力フィールドです。ただし、キュー・マネージャーは、MQPUT 呼び出しおよび MQPUT1 呼び出しで出力が生成されても MQMDE の該当するフィールドに値を戻しません。出力値が必要な場合には、そのアプリケーションでバージョン 2 の MQMD を使用する必要があります。
MQGET 呼び出しでアプリケーションからバージョン 1 の MQMD を提供した場合は、MQMDE の 1 つ以上のフィールドがデフォルト以外の値の場合に限り、キュー・マネージャーから返されるメッセージの先頭に MQMDE が付けられます。その場合、MQMD の Format フィールドに MQFMT_MD_EXTENSION という値が設定されて、MQMDE の存在が示されます。

キュー・マネージャーが MQMDE のフィールドに使用するデフォルト値は、表 2に示されているそれらのフィールドの初期値と同じです。

メッセージが伝送キューにある場合、MQMD 内の一部のフィールドは特定の値に設定されます。詳しくは、 MQXQH-伝送キュー・ヘッダーを参照してください。

メッセージ・コンテキスト

MQMD の特定のフィールドにはメッセージ・コンテキストが含まれます。メッセージ・コンテキストには、ID コンテキスト と発信元コンテキスト という 2 つのタイプがあります。一般に、

ID コンテキストは、最初に メッセージを書き込んだアプリケーションに関連したものです。
発信元コンテキストは、一番最近に メッセージを書き込んだアプリケーションに関連したものです。

これら 2 つのアプリケーションは同じアプリケーションのこともありますが、異なるアプリケーションであるというケースもあります (例えば、メッセージが 1 つのアプリケーションから別のアプリケーションに転送された場合)。

ID コンテキストと発信元コンテキストには一般に前述のような意味合いがありますが、MQMD 内のこの 2 つのタイプのコンテキスト・フィールドの内容は、メッセージが書き込まれた時点での MQPMO_*_CONTEXT オプションの指定によって異なります。その結果、ID コンテキストは必ずしも最初にメッセージを書き込んだアプリケーションに関連したものではなく、発信元コンテキストは必ずしも一番最近にメッセージを書き込んだアプリケーションに関連したものではありません。その内容は、アプリケーション・スイートの設計に応じて決まります。

メッセージ・チャネル・エージェント (MCA) がメッセージ・コンテキストを変更することは一切ありません。リモート・キュー・マネージャーからメッセージを受け取る MCA は、MQPUT または MQPUT1 呼び出しでコンテキスト・オプション MQPMO_SET_ALL_CONTEXT を使用します。これにより、受信側 MCA で、送信側 MCA からメッセージと一緒に伝達されてきたメッセージ・コンテキストを正確に保持することが可能になります。ただし、その結果として、起点コンテキストはメッセージの送信側の MCA および受信側の MCA のいずれにも関連付けられません。起点コンテキストは、メッセージを書き込んだ以前のアプリケーションを指します。すべての中間アプリケーションがメッセージ・コンテキストを渡している場合、起点コンテキストは発信元のアプリケーション自身を指します。

この説明の中で、コンテキスト・フィールドは、最初の説明のとおりに各フィールドが使用された場合として記述されています。メッセージ・コンテキストについて詳しくは、メッセージ・コンテキストを参照してください。

フィールド

注: 以下の表では、フィールドはアルファベット順ではなく使用順にグループ化されています。子トピックは、同じ順序に従います。

表 1. MQMD の場合の MQMD のフィールド
フィールド名と説明	定数の名前	定数の初期値 (存在する場合)
StrucId (構造 ID)	MQMD_STRUC_ID	`'MD'`
Version (構造体のバージョン番号)	MQMD_VERSION_1	`1`
レポート (レポート・メッセージのオプション)	MQRO_NONE	`0`
MsgType (メッセージ・タイプ)	MQMT_DATAGRAM	`8`
MQMD-Expiry フィールド (メッセージ存続時間)	MQEI_UNLIMITED	`-1`
MQMD-Feedback フィールド (フィードバックまたは理由コード)	MQFB_NONE	`0`
エンコード (メッセージ・データの数値エンコード)	MQENC_NATIVE	環境に依存
CodedCharSetId(メッセージデータの文字セット識別子)	MQCCSI_Q_MGR	`0`
Format (メッセージ・データの形式名)	MQFMT_NONE	ブランク
優先順位 (メッセージ優先順位)	MQPRI_PRIORITY_AS_Q_DEF	`-1`
持続性 (メッセージ持続性)	MQPER_PERSISTENCE_AS_Q_DEF	`2`
MQMD- MsgId フィールド (メッセージ ID)	MQMI_NONE	Null
CorrelId (相関 ID)	MQCI_NONE	Null
BackoutCount (バックアウト・カウンター)	なし	`0`
ReplyToQ(返信キューの名前)	なし	ヌル・ストリングまたはブランク
ReplyToQMgr(リプライキューマネージャの名前)	なし	ヌル・ストリングまたはブランク
UserIdentifier (ユーザー ID)	なし	ヌル・ストリングまたはブランク
AccountingToken (アカウンティング・トークン)	MQACT_NONE	Null
ApplIdentityData（IDに関するアプリケーションデータ）	なし	ヌル・ストリングまたはブランク
PutApplType（メッセージを置いたアプリケーションのタイプ）	MQAT_NO_CONTEXT	`0`
PutApplName（メッセージを置いたアプリケーションの名前）	なし	ヌル・ストリングまたはブランク
PutDate (メッセージが書き込まれた日付)	なし	ヌル・ストリングまたはブランク
PutTime (メッセージが書き込まれた時刻)	なし	ヌル・ストリングまたはブランク
ApplOriginData（オリジンに関するアプリケーションデータ）	なし	ヌル・ストリングまたはブランク
注: `Version` が MQMD_VERSION_2より前の場合、残りのフィールドは無視されます。
GroupId (グループ ID)	MQGI_NONE	Null
MsgSeqNumber（グループ内の論理メッセージのシーケンス番号）	なし	`1`
オフセット (論理メッセージの先頭からの物理メッセージ内のデータのオフセット)	なし	`0`
MQMD- MsgFlags フィールド (メッセージ・フラグ)	MQMF_NONE	`0`
OriginalLength (元のメッセージの長さ)	MQOL_UNDEFINED	`-1`
注: ヌル・ストリングまたはブランクの値は、C 言語ではヌル・ストリングを表し、他のプログラミング言語ではブランク文字を表します。 C プログラミング言語では、マクロ変数 MQMD_DEFAULT に表にリストされている値が設定されています。この変数を以下の方法で使用すると、構造体のフィールドに初期値を設定できます。 `MQMD MyMD = {MQMD_DEFAULT};`

言語ごとの宣言

MQMD の C 宣言

typedef struct tagMQMD MQMD;
struct tagMQMD {
  MQCHAR4   StrucId;           /* Structure identifier */
  MQLONG    Version;           /* Structure version number */
  MQLONG    Report;            /* Options for report messages */
  MQLONG    MsgType;           /* Message type */
  MQLONG    Expiry;            /* Message lifetime */
  MQLONG    Feedback;          /* Feedback or reason code */
  MQLONG    Encoding;          /* Numeric encoding of message data */
  MQLONG    CodedCharSetId;    /* Character set identifier of message
                                  data */
  MQCHAR8   Format;            /* Format name of message data */
  MQLONG    Priority;          /* Message priority */
  MQLONG    Persistence;       /* Message persistence */
  MQBYTE24  MsgId;             /* Message identifier */
  MQBYTE24  CorrelId;          /* Correlation identifier */
  MQLONG    BackoutCount;      /* Backout counter */
  MQCHAR48  ReplyToQ;          /* Name of reply queue */
  MQCHAR48  ReplyToQMgr;       /* Name of reply queue manager */
  MQCHAR12  UserIdentifier;    /* User identifier */
  MQBYTE32  AccountingToken;   /* Accounting token */
  MQCHAR32  ApplIdentityData;  /* Application data relating to
                                  identity */
  MQLONG    PutApplType;       /* Type of application that put the
                                  message */
  MQCHAR28  PutApplName;       /* Name of application that put the
                                  message */
  MQCHAR8   PutDate;           /* Date when message was put */
  MQCHAR8   PutTime;           /* Time when message was put */
  MQCHAR4   ApplOriginData;    /* Application data relating to origin */
  MQBYTE24  GroupId;           /* Group identifier */
  MQLONG    MsgSeqNumber;      /* Sequence number of logical message
                                  within group */
  MQLONG    Offset;            /* Offset of data in physical message
                                  from start of logical message */
  MQLONG    MsgFlags;          /* Message flags */
  MQLONG    OriginalLength;    /* Length of original message */
};

MQMD の COBOL 宣言

**   MQMD structure
  10 MQMD.
**    Structure identifier
   15 MQMD-STRUCID          PIC X(4).
**    Structure version number
   15 MQMD-VERSION          PIC S9(9) BINARY.
**    Options for report messages
   15 MQMD-REPORT           PIC S9(9) BINARY.
**    Message type
   15 MQMD-MSGTYPE          PIC S9(9) BINARY.
**    Message lifetime
   15 MQMD-EXPIRY           PIC S9(9) BINARY.
**    Feedback or reason code
   15 MQMD-FEEDBACK         PIC S9(9) BINARY.
**    Numeric encoding of message data
   15 MQMD-ENCODING         PIC S9(9) BINARY.
**    Character set identifier of message data
   15 MQMD-CODEDCHARSETID   PIC S9(9) BINARY.
**    Format name of message data
   15 MQMD-FORMAT           PIC X(8).
**    Message priority
   15 MQMD-PRIORITY         PIC S9(9) BINARY.
**    Message persistence
   15 MQMD-PERSISTENCE      PIC S9(9) BINARY.
**    Message identifier
   15 MQMD-MSGID            PIC X(24).
**    Correlation identifier
   15 MQMD-CORRELID         PIC X(24).
**    Backout counter
   15 MQMD-BACKOUTCOUNT     PIC S9(9) BINARY.
**    Name of reply queue
   15 MQMD-REPLYTOQ         PIC X(48).
**    Name of reply queue manager
   15 MQMD-REPLYTOQMGR      PIC X(48).
**    User identifier
   15 MQMD-USERIDENTIFIER   PIC X(12).
**    Accounting token
   15 MQMD-ACCOUNTINGTOKEN  PIC X(32).
**    Application data relating to identity
   15 MQMD-APPLIDENTITYDATA PIC X(32).
**    Type of application that put the message
   15 MQMD-PUTAPPLTYPE      PIC S9(9) BINARY.
**    Name of application that put the message
   15 MQMD-PUTAPPLNAME      PIC X(28).
**    Date when message was put
   15 MQMD-PUTDATE          PIC X(8).
**    Time when message was put
   15 MQMD-PUTTIME          PIC X(8).
**    Application data relating to origin
   15 MQMD-APPLORIGINDATA   PIC X(4).
**    Group identifier
   15 MQMD-GROUPID          PIC X(24).
**    Sequence number of logical message within group
   15 MQMD-MSGSEQNUMBER     PIC S9(9) BINARY.
**    Offset of data in physical message from start of logical message
   15 MQMD-OFFSET           PIC S9(9) BINARY.
**    Message flags
   15 MQMD-MSGFLAGS         PIC S9(9) BINARY.
**    Length of original message
   15 MQMD-ORIGINALLENGTH   PIC S9(9) BINARY.

MQMD の PL/I 宣言

dcl
 1 MQMD based,
  3 StrucId          char(4),       /* Structure identifier */
  3 Version          fixed bin(31), /* Structure version number */
  3 Report           fixed bin(31), /* Options for report messages */
  3 MsgType          fixed bin(31), /* Message type */
  3 Expiry           fixed bin(31), /* Message lifetime */
  3 Feedback         fixed bin(31), /* Feedback or reason code */
  3 Encoding         fixed bin(31), /* Numeric encoding of message
                                       data */
  3 CodedCharSetId   fixed bin(31), /* Character set identifier of
                                       message data */
  3 Format           char(8),       /* Format name of message data */
  3 Priority         fixed bin(31), /* Message priority */
  3 Persistence      fixed bin(31), /* Message persistence */
  3 MsgId            char(24),      /* Message identifier */
  3 CorrelId         char(24),      /* Correlation identifier */
  3 BackoutCount     fixed bin(31), /* Backout counter */
  3 ReplyToQ         char(48),      /* Name of reply queue */
  3 ReplyToQMgr      char(48),      /* Name of reply queue manager */
  3 UserIdentifier   char(12),      /* User identifier */
  3 AccountingToken  char(32),      /* Accounting token */
  3 ApplIdentityData char(32),      /* Application data relating to
                                       identity */
  3 PutApplType      fixed bin(31), /* Type of application that put the
                                       message */
  3 PutApplName      char(28),      /* Name of application that put the
                                       message */
  3 PutDate          char(8),       /* Date when message was put */
  3 PutTime          char(8),       /* Time when message was put */
  3 ApplOriginData   char(4),       /* Application data relating to
                                       origin */
  3 GroupId          char(24),      /* Group identifier */
  3 MsgSeqNumber     fixed bin(31), /* Sequence number of logical
                                       message within group */
  3 Offset           fixed bin(31), /* Offset of data in physical
                                       message from start of logical
                                       message */
  3 MsgFlags         fixed bin(31), /* Message flags */
  3 OriginalLength   fixed bin(31); /* Length of original message */

MQMD の高水準アセンブラー宣言

MQMD                   DSECT
MQMD_STRUCID           DS   CL4   Structure identifier
MQMD_VERSION           DS   F     Structure version number
MQMD_REPORT            DS   F     Options for report messages
MQMD_MSGTYPE           DS   F     Message type
MQMD_EXPIRY            DS   F     Message lifetime
MQMD_FEEDBACK          DS   F     Feedback or reason code
MQMD_ENCODING          DS   F     Numeric encoding of message data
MQMD_CODEDCHARSETID    DS   F     Character set identifier of message
*                                 data
MQMD_FORMAT            DS   CL8   Format name of message data
MQMD_PRIORITY          DS   F     Message priority
MQMD_PERSISTENCE       DS   F     Message persistence
MQMD_MSGID             DS   XL24  Message identifier
MQMD_CORRELID          DS   XL24  Correlation identifier
MQMD_BACKOUTCOUNT      DS   F     Backout counter
MQMD_REPLYTOQ          DS   CL48  Name of reply queue
MQMD_REPLYTOQMGR       DS   CL48  Name of reply queue manager
MQMD_USERIDENTIFIER    DS   CL12  User identifier
MQMD_ACCOUNTINGTOKEN   DS   XL32  Accounting token
MQMD_APPLIDENTITYDATA  DS   CL32  Application data relating to identity
MQMD_PUTAPPLTYPE       DS   F     Type of application that put the
*                                 message
MQMD_PUTAPPLNAME       DS   CL28  Name of application that put the
*                                 message
MQMD_PUTDATE           DS   CL8   Date when message was put
MQMD_PUTTIME           DS   CL8   Time when message was put
MQMD_APPLORIGINDATA    DS   CL4   Application data relating to origin
MQMD_GROUPID           DS   XL24  Group identifier
MQMD_MSGSEQNUMBER      DS   F     Sequence number of logical message
*                                 within group
MQMD_OFFSET            DS   F     Offset of data in physical message
*                                 from start of logical message
MQMD_MSGFLAGS          DS   F     Message flags
MQMD_ORIGINALLENGTH    DS   F     Length of original message
*
MQMD_LENGTH            EQU  *-MQMD
                       ORG  MQMD
MQMD_AREA              DS   CL(MQMD_LENGTH)

MQMD の Visual Basic 宣言

Type MQMD
  StrucId          As String*4  'Structure identifier'
  Version          As Long      'Structure version number'
  Report           As Long      'Options for report messages'
  MsgType          As Long      'Message type'
  Expiry           As Long      'Message lifetime'
  Feedback         As Long      'Feedback or reason code'
  Encoding         As Long      'Numeric encoding of message data'
  CodedCharSetId   As Long      'Character set identifier of message'
                                'data'
  Format           As String*8  'Format name of message data'
  Priority         As Long      'Message priority'
  Persistence      As Long      'Message persistence'
  MsgId            As MQBYTE24  'Message identifier'
  CorrelId         As MQBYTE24  'Correlation identifier'
  BackoutCount     As Long      'Backout counter'
  ReplyToQ         As String*48 'Name of reply queue'
  ReplyToQMgr      As String*48 'Name of reply queue manager'
  UserIdentifier   As String*12 'User identifier'
  AccountingToken  As MQBYTE32  'Accounting token'
  ApplIdentityData As String*32 'Application data relating to identity'
  PutApplType      As Long      'Type of application that put the'
                                'message'
  PutApplName      As String*28 'Name of application that put the'
                                'message'
  PutDate          As String*8  'Date when message was put'
  PutTime          As String*8  'Time when message was put'
  ApplOriginData   As String*4  'Application data relating to origin'
  GroupId          As MQBYTE24  'Group identifier'
  MsgSeqNumber     As Long      'Sequence number of logical message'
                                'within group'
  Offset           As Long      'Offset of data in physical message'
                                'from start of logical message'
  MsgFlags         As Long      'Message flags'
  OriginalLength   As Long      'Length of original message'
End Type