MQINQMP-查詢訊息內容

MQINQMP 呼叫會傳回訊息內容的值。

語法

MQINQMP (Hconn、 Hmsg、 InqPropOpts、 名稱、 PropDesc、 類型、 ValueLength、 值、 DataLength、 CompCode、 Reason)

參數

赫科恩
類型 :MQHCONN-輸入

此控點代表佇列管理程式的連線。 Hconn 的值必須符合用來建立 Hmsg 參數中所指定訊息控點的連線控點。

如果訊息控點是使用 MQHC_UNASSOCIED_HCONN 建立的，則必須在查詢訊息控點內容的執行緒上建立有效連線，否則呼叫會因 MQRC_CONNECTION_BROKEN 而失敗。

Hmsg
類型 :MQHMSG-輸入

這是要查詢的訊息控點。 前一個 MQCRTMH 呼叫已傳回值。

InqProp選項
類型 :MQIMPO-輸入/輸出

如需詳細資料，請參閱 MQIMPO 資料類型。

名稱
類型 :MQCHARV-輸入/輸出

要查詢的內容名稱。

如果找不到具有此名稱的內容，則呼叫會失敗，原因為 MQRC_PROPERTY_NOT_AVAILABLE。

您可以在內容名稱結尾使用萬用字元百分比符號 (%)。 萬用字元符合零個以上字元，包括句點 (.) 字元。 這可讓應用程式查詢許多內容的值。 使用選項 MQIMPO_INQ_FIRST 呼叫 MQINQMP 以取得第一個相符內容，並再次使用選項 MQIMPO_INQ_NEXT 以取得下一個相符內容。 當沒有其他相符內容可用時，呼叫會失敗，且 MQRC_PROPERTY_NOT_AVAILABLE。 如果使用所傳回內容名稱的位址或偏移來起始設定 InqPropOpts 結構的 ReturnedName 欄位，則會在從 MQINQMP 傳回具有相符內容名稱的內容時完成此作業。 如果 InqPropOpts 結構中 ReturnedName 的 VSBufSize 欄位小於所傳回內容名稱的長度，則完成碼會設定 MQCC_FAILED ，原因為 MQRC_PROPERTY_NAME_TOO_BIG。

會傳回具有已知同義字的內容，如下所示:
  1. 字首為 "mqps" 的內容。 會以 IBM® MQ 內容名稱傳回。 例如， "MQTopicString" 是傳回的名稱，而不是 "mqps.Top"
  2. 字首為 "jms" 的內容。 或 "mcd"。 會以 JMS 標頭欄位名稱傳回，例如 "JMSExpiration" 是傳回的名稱，而不是 "jms.Exp"。
  3. 字首為 "usr." 的內容 會傳回不含該字首的，例如，傳回 "Color" 而不是 "usr.Color"。
具有同義字的內容只會傳回一次。

在 C 程式設計語言中，下列巨集變數定義為查詢所有內容，然後查詢開頭為 "usr." 的所有內容:

MQPROP_INQUIRE_ALL
查詢訊息的所有內容。
MQPROP_INQUIRE_ALL 可透過下列方式使用:

MQCHARV Name = {MQPROP_INQUIRE_ALL};
MQPROP_INQUIRE_ALL_USR
查詢啟動 "usr." 之訊息的所有內容。 傳回的名稱不含 "usr."。 字首。

如果已指定 MQIMP_INQ_NEXT ，但自前一次呼叫後名稱已變更，或這是第一次呼叫，則會隱含 MQIMPO_INQ_FIRST。

如需使用內容名稱的進一步相關資訊，請參閱 內容名稱 及 內容名稱限制 。

PropDesc
類型 :MQPD-輸出

此結構用來定義內容的屬性，包括不支援內容時所發生的情況、內容所屬的訊息環境定義，以及內容應該複製到哪些訊息。 如需此結構的詳細資料，請參閱 MQPD 。

類型
類型 :MQLONG-輸入/輸出

從 MQINQMP 呼叫返回時，此參數會設為資料類型 值。 資料類型可以是下列任何一項:

MQ 類型 _ 布林
布林。
MQTYPE_BYTE_STRING
位元組字串。
MQTYPE_INT8
8 位元帶正負號的整數。
MQTYPE_INT16
16 位元帶正負號的整數。
MQTYPE_INT32
32 位元，帶正負號的整數。
MQTYPE_INT64
64 位元帶正負號的整數。
MQTYPE_FLOAT32
32 位元浮點數字。
MQTYPE_FLOAT64
64 位元浮點數字。
MQTYPE_STRING
字串。
MQTYPE_NULL
內容存在，但具有空值。

如果無法辨識內容值的資料類型，則會傳回 MQTYPE_STRING ，並將值的字串表示法放置在 值 區域中。 資料類型的字串表示法可在 InqPropOpts 參數的 TypeString 欄位中找到。 傳回警告完成碼，原因為 MQRC_PROP_TYPE_NOT_SUPPORTED。

此外，如果指定選項 MQIMPO_CONVERT_TYPE ，則會要求轉換內容值。 使用 類型 作為輸入，以指定您要傳回內容的資料類型。 如需資料類型轉換的詳細資料，請參閱 MQIMPO 結構之 MQIMPO_CONVERT_TYPE 選項的說明。

如果您不要求類型轉換，則可以在輸入上使用下列值:
MQTYPE_AS_SET
會傳回內容的值，而不轉換其資料類型。
ValueLength
類型 :MQLONG-輸入

「值」區域的長度 (以位元組為單位)。 對於您不需要所傳回值的內容，請指定零。 這些內容可以是由應用程式設計成具有空值或空字串的內容。 如果已指定 MQIMPO_QUERY_LENGTH 選項，也請指定零; 在此情況下，不會傳回任何值。

值
類型 :MQBYTEx ValueLength -輸出

這是要包含所查詢內容值的區域。 緩衝區應該在適合所傳回值的界限上對齊。 如果無法這樣做，則在稍後存取值時可能會導致錯誤。

如果 ValueLength 小於內容值的長度，則會將儘可能多的內容值移入 值 中，且呼叫會失敗，並出現完成碼 MQCC_FAILED 及原因 MQRC_PROPERTY_VALUE_TOO_BIG。

值 中資料的字集是由 InqPropOpts 參數中的 ReturnedCCSID 欄位所提供。 值 中的資料編碼由 InqPropOpts 參數中的 ReturnedEncoding 欄位提供。

在 C 程式設計語言中，參數宣告為 void 的指標; 任何資料類型的位址都可以指定為參數。

如果 ValueLength 參數為零，則不會參照 值 ，且以 C 或 System/390 組譯器撰寫的程式所傳遞的值可以是空值。

DataLength
類型 :MQLONG-輸出

這是在 值 區域中傳回的實際內容值長度 (以位元組為單位)。

如果 DataLength 小於內容值長度，則 MQINQMP 呼叫傳回時仍會填入 DataLength 。 這可讓應用程式判斷容納內容值所需的緩衝區大小，然後以適當大小的緩衝區重新發出呼叫。

也可以傳回下列值。

如果 Type 參數設為 MQTYPE_STRING 或 MQTYPE_BYTE_STRING:
MQVL_EMPTY_STRING
內容存在，但未包含任何字元或位元組。
CompCode
類型 :MQLONG-輸出
完成碼; 它是下列其中一項:
MQCC_OK
順利完成。
MQCC_WARNING
警告 (局部完成)。
MQCC_FAILED
呼叫失敗。
原因
類型 :MQLONG-輸出
如果 CompCode 是 MQCC_OK:
MQRC_NONE
(0 ， X'000 ') 沒有理由報告。
如果 CompCode 是 MQCC_WARNING:
MQRC_PROP_NAME_NOT_CONVERTED
(2492 ， X'09BC') 未轉換傳回的內容名稱。
MQRC_PROP_VALUE_NOT_CONVERTED
(2466 ， X'09A2') 未轉換內容值。
MQRC_PROP_TYPE_NOT_SUPPORTED
(2467 ， X'09A3') 不支援內容資料類型。
MQRC_RFH_FORMAT_ERROR
(2421 ， X'0975 ') 無法剖析包含內容的 MQRFH2 資料夾。
如果 CompCode 是 MQCC_FAILED:
MQRC_ADAPTER_NOT_AVAILABLE
(2204 ， X'089C') 配接器無法使用。
MQRC_ADAPTER_SERV_LOAD_ERROR
(2130 ， X'0852 ') 無法載入配接卡服務模組。
MQRC_ASDID_MISMATCH
(2157 ， X'086D') 主要和起始 ASID 不同。
MQRC_BUFFER_ERROR
(2004 ， X'07D4') 值參數無效。
MQRC_BUFFER_LENGTH_ERROR
(2005 ， X'07D5') 值長度參數無效。
MQRC_CALL_IN_PROGRESS
(2219 ， X'08AB') 在前一個呼叫完成之前輸入的 MQI 呼叫。
MQRC_CONNECTION_BROKEN
(2009 ， X'07D9') 與佇列管理程式的連線遺失。
MQRC_DATA_LENGTH_ERROR
(2010 ， X'07DA') 資料長度參數無效。
MQRC_IMPO_ERROR
(2464 ， X'09A0') 查詢訊息內容選項結構無效。
MQRC_HMSG_ERROR
(2460 ， X'099C') 訊息控點無效。
MQRC_MSG_HANDLE_IN_USE
(2499 ， X'09C3') 訊息控點已在使用中。
MQRC_OPTIONS_ERROR
(2046 ， X'07F8') 選項無效或不一致。
MQRC_PD_ERROR
(2482 ， X'09B2') 內容描述子結構無效。
MQRC_PROP_CONV_NOT_SUPPORTED
(2470 ， X'09A6') 不支援從實際轉換為所要求的資料類型。
MQRC_PROPERTY_NAME_ERROR
(2442 ， X'098A') 內容名稱無效。
MQRC_PROPERTY_NAME_TOO_BIG
(2465 ， X'09A1') 傳回名稱緩衝區的內容名稱太大。
MQRC_PROPERTY_NOT_AVAILABLE
(2471 ， X'09A7) 內容無法使用。
MQRC_PROPERTY_VALUE_TOO_BIG
(2469 ， X'09A5') 內容值對「值」區域而言太大。
MQRC_PROP_NUMBER_FORMAT_ERROR
(2472 ， X'09A8') 在值資料中發現數字格式錯誤。
MQRC_PROPERTY_TYPE_ERROR
(2473 ， X'09A9') 所要求的內容類型無效。
MQRC_SOURCE_CCSID_ERROR
(2111 ， X'083F') 內容名稱編碼字集 ID 無效。
MQRC_STORAGE_NOT_AVAILABLE
(2071 ， X'0871 ') 可用的儲存體不足。
MQRC_UNEXPECTED_ERROR
(2195 ， X'0893 ') 發生非預期的錯誤。

如需這些代碼的詳細資訊，請參閱 訊息及原因碼。

C 呼叫


MQINQMP (Hconn, Hmsg, &InqPropOpts, &Name, &PropDesc, &Type,
ValueLength, Value, &DataLength, &CompCode, &Reason);
宣告參數如下:

MQHCONN Hconn;       /* Connection handle */
MQHMSG  Hmsg;        /* Message handle */
MQIMPO  InqPropOpts; /* Options that control the action of MQINQMP */
MQCHARV Name;        /* Property name */
MQPD    PropDesc;    /* Property descriptor */
MQLONG  Type;        /* Property data type */
MQLONG  ValueLength; /* Length in bytes of the Value area */
MQBYTE  Value[n];    /* Area to contain the property value */
MQLONG  DataLength;  /* Length of the property value */
MQLONG  CompCode;    /* Completion code */
MQLONG  Reason;      /* Reason code qualifying CompCode */

COBOL 呼叫


CALL 'MQINQMP' USING HCONN, HMSG, INQMSGOPTS, NAME, PROPDESC, TYPE,
VALUELENGTH, VALUE, DATALENGTH, COMPCODE, REASON.
宣告參數如下:

**   Connection handle
 01  HCONN       PIC S9(9) BINARY.
**   Message handle
 01  HMSG		    PIC S9(18) BINARY.
**   Options that control the action of MQINQMP
 01  INQMSGOPTS.
     COPY CMQIMPOV.
**   Property name
 01  NAME.
     COPY CMQCHRVV.
**   Property descriptor
 01  PROPDESC.
     COPY CMQPDV.
**   Property data type
 01  TYPE        PIC S9(9) BINARY.
**   Length in bytes of the VALUE area
 01  VALUELENGTH PIC S9(9) BINARY.
**   Area to contain the property value
 01  VALUE       PIC X(n).
**   Length of the property value
 01  DATALENGTH  PIC S9(9) BINARY.
**   Completion code
 01  COMPCODE    PIC S9(9) BINARY.
**   Reason code qualifying COMPCODE
 01  REASON      PIC S9(9) BINARY.

PL/I 呼叫


call MQINQMP (Hconn, Hmsg, InqPropOpts, Name, PropDesc, Type,
ValueLength, Value, DataLength, CompCode, Reason);
宣告參數如下:

dcl Hconn       fixed bin(31);  /* Connection handle */
dcl Hmsg        fixed bin(63);  /* Message handle */
dcl InqPropOpts like MQIMPO;    /* Options that control the action of MQINQMP */
dcl Name        like MQCHARV;   /* Property name */
dcl PropDesc    like MQPD;      /* Property descriptor */
dcl Type        fixed bin (31); /* Property data type */
dcl ValueLength fixed bin (31); /* Length in bytes of the Value area */
dcl Value       char (n);       /* Area to contain the property value */
dcl DataLength  fixed bin (31); /* Length of the property value */
dcl CompCode    fixed bin (31); /* Completion code */
dcl Reason      fixed bin (31); /* Reason code qualifying CompCode */

High Level Assembler 呼叫


CALL MQINQMP,(HCONN,HMSG,INQMSGOPTS,NAME,PROPDESC,TYPE,
VALUELENGTH,VALUE,DATALENGTH,COMPCODE,REASON)
宣告參數如下:

HCONN        DS         F     Connection handle
HMSG         DS         D     Message handle
INQMSGOPTS   CMQIMPOA   ,     Options that control the action of MQINQMP
NAME         CMQCHRVA   ,     Property name
PROPDESC     CMQPDA     ,     Property descriptor
TYPE         DS         F     Property data type
VALUELENGTH  DS         F     Length in bytes of the VALUE area
VALUE        DS         CL(n) Area to contain the property value
DATALENGTH   DS         F     Length of the property value
COMPCODE     DS         F     Completion code
REASON       DS         F     Reason code qualifying COMPCODE