MQSUB-登錄訂閱

使用 MQSUB 呼叫來登錄特定主題的應用程式訂閱。

語法

MQSUB (Hconn、 SubDesc、 Hobj、 Hsub、 Compcode、 Reason)

參數

Hconn
類型 :MQHCONN-輸入

此控點代表佇列管理程式的連線。 前一個 MQCONN 或 MQCONNX 呼叫已傳回 Hconn 的值。

在 z/OS® for CICS® 應用程式上，以及在 IBM® i for 以相容模式執行的應用程式上，可以省略 MQCONN 呼叫，並針對 Hconn 指定下列值:
MQHC_DEF_HCONN
預設連線控點。
[IBMi]重要事項: 如果您仍在使用相容模式，請考量重新編譯應用程式，並改用靜態連結呼叫。 請參閱 IBM i上 RPG 應用程式的相容模式
SubDesc
類型 :MQSD-輸入/輸出

此結構可識別應用程式正在登錄的使用中物件。 如需相關資訊，請參閱 MQSD-訂閱描述子 。

HOBJ
類型 :MQHOBJ-輸入/輸出

此控點代表為了取得傳送至此訂閱的訊息而建立的存取權。 這些訊息可以儲存在特定佇列上，或佇列管理程式可以管理其儲存體而不使用特定佇列。

若要使用特定佇列，您必須在建立訂閱時將它與訂閱相關聯。 您可以使用兩種方式來執行此動作：
  • 透過使用 DEFINE SUB MQSC 指令，並提供該指令與佇列物件名稱。
  • 使用 MQSO_CREATE 呼叫 MQSUB 時提供此控點
    如果提供此控點作為呼叫上的輸入參數，則它必須是從佇列的前一個 MQOPEN 呼叫中使用下列至少一個選項所傳回的有效物件控點:
    • MQOO_INPUT_ *
    • MQ 瀏覽
    • MQOO_OUTPUT (如果佇列是遠端佇列)
    如果不是這種情況，則呼叫會失敗，並產生 MQRC_HOBJ_ERROR。 它不能是解析為主題物件之別名佇列的物件控點。 如果是這樣，則呼叫會失敗，並產生 MQRC_HOBJ_ERROR。

如果佇列管理程式要管理傳送至此訂閱的訊息儲存體，則應該在建立訂閱時使用 MQSO_MANAGED 選項來設定此值。 然後，佇列管理程式會傳回此控點作為呼叫的輸出參數。 傳回的控點稱為受管理控點。 如果指定 MQHO_NONE 但未指定 MQSO_MANAGED ，則呼叫會失敗，並產生 MQRC_HOBJ_ERROR。

當佇列管理程式將受管理控點傳回給您時，您可以在具有或不具有瀏覽選項的 MQGET 或 MQCB 呼叫、MQINQ 呼叫或 MQCLOSE 上使用它。 您無法在 MQPUT、MQSUB、MQSET 上使用它; 嘗試這樣做會失敗，並產生 MQRC_NOT_OPEN_FOR_OUTPUT、MQRC_HOBJ_ERROR 或 MQRC_NOT_OPEN_FOR_SET。

如果正在使用 MQSD 結構中的 MQSO_RESUME 選項來回復此訂閱，則可以透過將 MQSO_MANAGED 設為 MQHO_NONE ，將控點傳回此參數中的應用程式。 不論訂閱是否使用受管理控點，您都可以執行此動作，而且提供使用 DEFINE SUB 所建立的訂閱與該指令上所定義的訂閱佇列控點。 在回復以管理方式建立的訂閱的情況下，佇列會以 MQOO_INPUT_AS_Q_DEF 和 MQOO_BROWSE 開啟。 如果您需要指定其他選項，應用程式必須明確開啟訂閱佇列，並在呼叫時提供物件控點。 如果開啟佇列時發生問題，則呼叫會失敗，並產生 MQRC_INVALID_DESTINATION。 如果提供 Hobj ，則它必須相當於原始 MQSUB 呼叫中的 Hobj 。 這表示如果提供從 MQOPEN 呼叫傳回的物件控點，則該控點必須與先前使用的佇列相同。 如果不是相同的佇列，則呼叫會失敗，並產生 MQRC_HOBJ_ERROR。

如果使用 MQSD 結構中的 MQSO_ALTER 選項來變更此訂閱，則可以提供不同的 Hobj 。 任何已遞送至佇列且先前透過此參數所識別的發佈都會留在該佇列上，而且如果 Hobj 參數現在代表不同的佇列，則應用程式會負責擷取那些訊息。

下表彙總此參數與各種訂閱選項的使用:
選項 Hobj 說明
MQSO_CREATE + MQSO_MANAGED 輸入時忽略 建立訂閱並儲存佇列管理程式所管理的訊息
MQSO_CREATE 有效的物件控點 建立訂閱，以提供特定佇列作為訊息的目的地。
MQ 回復 MQHO_NONE 回復先前建立的訂閱 (不論它是否受管理) ，並讓佇列管理程式傳回物件控點供應用程式使用。
MQ 回復 有效、相符、物件控點 回復先前建立的訂閱，使用特定佇列作為訊息的目的地，並使用具有特定開啟選項的物件控點。
MQSO_ALTER + MQSO_MANAGED MQHO_NONE 變更先前使用特定佇列的現有訂閱，因此它現在是受管理訂閱。 無法變更目的地 (受管理或未受管理) 的類別。
MQSO_ALTER 有效的物件控點 變更現有訂閱 (不論是否受管理) ，以便它現在使用特定佇列。 未使用 MQSO_MANAGED 選項時，可以變更提供的佇列，但無法變更目的地的類別 (受管理或未受管理)。

不論是否已提供或傳回，都必須在後續的 MQGET 或 MQCB 呼叫上指定 Hobj ，以接收傳送至此訂閱的發佈訊息。

當對 Hobj 控點發出 MQCLOSE 呼叫時，或當定義控點範圍的處理單元終止時 (直到應用程式中斷連線為止) ，該控點不再有效。 傳回的物件控點範圍與呼叫上指定的連線控點範圍相同。 如需控點範圍的相關資訊，請參閱 Hconn (MQHCONN)-output 。 Hobj 控點的 MQCLOSE 不會影響 Hsub 控點。

HSub
類型 :MQHOBJ-輸出
此控點代表已建立的訂閱。 它可以用於兩個進一步的作業:
  • 它可以在後續的 MQSUBRQ 呼叫上使用，以要求在建立訂閱時使用 MQSO_PUBLICATIONS_ON_REQUEST 選項時傳送發佈。
  • 它可以在後續的 MQCLOSE 呼叫中使用，以移除已建立的訂閱。 當發出 MQCLOSE 呼叫時，或當定義控點範圍的處理單元終止時， Hsub 控點即不再有效。 傳回的物件控點範圍與呼叫上指定的連線控點範圍相同。 Hsub 控點的 MQCLOSE 不會影響 Hobj 控點。

此控點無法傳遞至 MQGET 或 MQCB 呼叫。 您必須使用 Hobj 參數。 您無法在 MQCLOSE 或 MQSUBRQ 以外的任何 IBM MQ 呼叫上使用此控點。 將此控點傳遞至任何其他 IBM MQ 呼叫會導致 MQRC_HOBJ_ERROR。

CompCode
類型 :MQLONG-輸出
完成碼; 它是下列其中一項:
MQCC_OK
順利完成
MQCC_WARNING
警告 (局部完成)
MQCC_FAILED
通話失敗
原因
類型 :MQLONG-輸出

定義 CompCode的原因碼。

如果 CompCode 是 MQCC_OK ，則原因碼如下:
MQRC_NONE
(0 ， X'000 ') 沒有理由報告。
如果 CompCode 是 MQCC_FAILED ，則原因碼為下列其中一項:
MQRC_CLUSTER_RESOLUTION_ERROR
(2189 ， X'88D') 叢集名稱解析失敗。
MQRC_DURABILITY_NOT_ALLOWED
2436 (X'0984 ') 使用 MQSO_DURABLE 選項的 MQSUB 呼叫失敗。
MQRC_FUNCTION_NOT_SUPPORTED
2298 (X'08FA') 在現行環境中無法使用所要求的功能。
MQRC_HOBJ_ERROR
2019 (X'07E3') 物件控點 Hobj 無效。
MQRC_IDENTITY_MISMATCH
2434 (X'0982 ') 訂閱名稱符合現有訂閱。
MQRC_NOT_AUTHORIZED
2035 (X'07F3') 使用者未獲授權執行作業。
MQRC_NO_SUBSCRIPTION
2428 (X'097C') 所識別的訂閱名稱不存在。
MQRC_OBJECT_STRING_ERROR
2441 (X'0989 ') Objectstring 欄位無效。
MQRC_OPTIONS_ERROR
2046 (X'07FE') 選項參數或欄位包含無效的選項或無效的選項組合。
MQRC_Q_MGR_QUIESCING
2161 (X'0871 ') 佇列管理程式靜止中。
MQRC_RECONNECT_Q_MGR_REQD
2555 (X'09FB' X) 需要 MQCNO_RECONNECT_Q_MGR 選項。
MQRC_RETAINED_MSG_Q_ERROR
2525 (X'09DD') 無法擷取已訂閱主題字串的已保留發佈資訊。
MQRC_RETAINED_NOT_DELIVERED
2526 (X'09DE') 已訂閱主題字串的保留發佈資訊無法遞送至訂閱目的地佇列，也無法遞送至無法傳送郵件的佇列。
MQRC_SD_ERROR
2424 (X'0978 ') 訂閱描述子 (MQSD) 無效。
MQRC_SELECTION_NOT_AVAILABLE
2551 (X'09F7') 選取字串未遵循 IBM MQ 選取器語法，且沒有可用的延伸訊息選取提供者。
MQRC_SELECTION_STRING_ERROR
2519 (X'09D7') 必須依照 MQCHARV 結構文件的說明來指定選取字串。
MQRC_SELECTOR_SYNTAX_ERROR
2459 (X'099B') 已發出 MQOPEN、 MQPUT1或 MQSUB 呼叫，但指定了包含語法錯誤的選取字串。
MQRC_SUB_USER_DATA_ERROR
2431 (X'097F') SubUser資料欄位無效。
MQRC_SUB_NAME_ERROR
2440 (X'0988 ') SubName 欄位無效。
MQRC_SUB_ALREADY_EXISTS
2432 (X'0980 ') 訂閱已存在。
MQRC_SUB_USER_DATA_ERROR
2431 (X'097F') SubUser資料欄位無效。
MQRC_TOPIC_STRING_ERROR
2425 (X'0979 ') 主題字串無效。
MQRC_UNKNOWN_OBJECT_NAME
2085 (X'0825 ') 找不到 MQSD ObjectName 欄位中所識別的物件。

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

使用注意事項

  • 訂閱是對主題進行，使用預先定義主題物件的簡稱、主題字串的完整名稱來命名，或由兩個部分連結而成。 請參閱 MQSD-訂閱描述子中 ObjectName 及 ObjectString 的說明。
  • 當發出 MQSUB 呼叫時，佇列管理程式會執行安全檢查，以驗證執行應用程式的使用者 ID 在允許存取之前具有適當的權限層次。 適當的主題物件位於主題階層中，且會對此主題物件進行權限檢查，以確保已設定訂閱權限。 如果未使用 MQSO_MANAGED 選項，則會對目的地佇列進行權限檢查，以確保設定輸出的權限。 如果使用 MQSO_MANAGED 選項，則不會對受管理佇列進行輸出或查詢存取權的權限檢查。
  • 如果您未提供 Hobj 作為輸入， MQSUB 呼叫會配置兩個控點: 物件控點 (Hobj) 和訂閱控點 (Hsub)。
  • 當使用 MQSO_MANAGED 選項時，會在 MQSUB 呼叫中傳回 Hobj ，可以進行查詢，以找出諸如「取消」臨界值及「過多取消重新排入佇列」名稱之類的屬性。 您也可以查詢受管理佇列的名稱，但不得嘗試直接開啟此佇列。
  • 訂閱可以分組，即使多個群組符合發佈，也只容許將單一發佈遞送至訂閱群組。 訂閱會使用 MQSO_GROUP_SUB 選項進行分組，為了將訂閱分組，它們必須是
    • 在相同的佇列管理程式上使用相同的具名佇列 (不使用 MQSO_MANAGED 選項)-由 MQSUB 呼叫上的 Hobj 參數代表
    • 共用相同的 SubCorrelID
    • 屬於相同的 SubLevel
    這些屬性定義視為在群組中的訂閱集，同時也是在訂閱分組時無法變更的屬性。 變更 SubLevel 會導致 MQRC_SUBLEVEL_NOT_ALTERABLE ，而變更任何其他 (如果未分組訂閱則可以變更) 會導致 MQRC_GROUPING_NOT_ALTERABLE。
  • 順利完成 MQSUB 呼叫並不表示動作已完成。 若要檢查此呼叫是否已完成，請參閱 檢查分散式網路的非同步指令是否已完成中的 DEFINE SUB 步驟。
  • 從使用 MQSO_RESUME 選項的 MQSUB 呼叫傳回時，會填寫 MQSD 中的欄位。 傳回的 MQSD 可以直接傳遞至 MQSUB 呼叫，該呼叫會使用 MQSO_ALTER 選項，且您需要對套用至 MQSD 的訂閱進行任何變更。 如表格中所述，部分欄位有特殊考量。
    MQSUB 的 MQSD 輸出
    MQSD 中的欄位名稱 特殊考量
    存取或建立選項 從 MQSUB 呼叫返回時可以重設部分選項。 如果您隨後在 MQSUB 呼叫中重複使用 MQSD ，則必須明確設定您需要的選項。
    延續性選項、目的地選項、登錄選項及萬用字元選項 視需要設定這些選項
    發佈選項 這些選項會適當地設定，但 MQSO_NEW_PUBLICATIONS_ONLY 除外，它只適用於 MQSO_CREATE。
    其他選項 從 MQSUB 呼叫傳回時，這些選項保持不變。 它們控制如何發出 API 呼叫，且不會與訂閱一起儲存。 必須在重複使用 MQSD 的任何後續 MQSUB 呼叫上視需要設定它們。
    ObjectName 從 MQSUB 呼叫傳回時，此僅輸入欄位保持不變。
    ObjectString 從 MQSUB 呼叫傳回時，此僅輸入欄位保持不變。 如果提供緩衝區，則會在 ResObjectString 欄位中傳回使用的完整主題名稱。
    AlternateUserId 和 AlternateSecurityId 從 MQSUB 呼叫傳回時，這些僅輸入欄位保持不變。 它們控制如何發出 API 呼叫，且不會與訂閱一起儲存。 它們必須在重複使用 MQSD 的任何後續 MQSUB 呼叫上視需要設定。
    SubExpiry 使用 MQSO_RESUME 選項從 MQSUB 呼叫返回時，此欄位會設為訂閱的原始到期，而不是剩餘到期時間。 然後，如果您使用 MQSO_ALTER 選項在 MQSUB 呼叫中重複使用 MQSD ，則會重設訂閱的期限，以重新開始倒數。
    SubName 此欄位是 MQSUB 呼叫的輸入欄位，在輸出時不會變更。
    SubUserData and SelectionString

    如果提供緩衝區，則在 MQSUB 呼叫使用 MQSO_RESUME 選項輸出時，會傳回這些可變長度欄位，同時在 VSBufSize中也會傳回正的緩衝區長度。 如果未提供任何緩衝區，則只會在 MQCHARV 的 VSLength 欄位中傳回長度。 如果提供的緩衝區小於傳回欄位所需的空間，則只會在提供的緩衝區中傳回 VSBufSize 個位元組。

    然後，如果您使用 MQSO_ALTER 選項在 MQSUB 呼叫中重複使用 MQSD ，且未提供緩衝區，但提供非零 VSLength ，如果該長度符合欄位的現有長度，則不會對欄位進行任何變更。
    SubCorrelID 和 PubAccounting記號

    如果您不使用 MQSO_SET_CORREL_ID ，則佇列管理程式會產生 SubCorrelId 。 如果您不使用 MQSO_SET_IDENTITY_CONTEXT ，則佇列管理程式會產生 PubAccountingToken 。

    使用 MQSO_RESUME 選項，在 MQSD 中從 MQSUB 呼叫傳回這些欄位。 如果由佇列管理程式產生，則會使用 MQSO_CREATE 或 MQSO_ALTER 選項，在 MQSUB 呼叫上傳回產生的值。
    PubPriority, SubLevel & PubApplIdentityData 這些欄位會在 MQSD 中傳回。
    ResObject字串 如果提供緩衝區，則 MQSD 中只會傳回此輸出欄位。

C 呼叫


MQSUB (Hconn, &SubDesc, &Hobj, &Hsub, &CompCode, &Reason)
宣告參數如下:

MQHCONN Hconn;    /* Connection handle */
MQSD    SubDesc;  /* Subscription descriptor */
MQHOBJ  Hobj;     /* Object handle */
MQHOBJ  Hsub;     /* Subscription handle */
MQLONG  CompCode; /* Completion code */
MQLONG  Reason;   /* Reason code qualifying CompCode */

COBOL 呼叫


CALL 'MQSUB' USING HCONN, SUBDESC, HOBJ, HSUB, COMPCODE, REASON.
宣告參數如下:

**   Connection handle
 01  HCONN    PIC S9(9) BINARY.
**   Subscription descriptor
 01  SUBDESC.
     COPY CMQSDV.
**   Object handle
 01  HOBJ     PIC S9(9) BINARY.
**   Subscription handle
 01  HSUB     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 MQSUB (Hconn, SubDesc, Hobj, Hsub, CompCode, Reason)
宣告參數如下:

dcl Hconn    fixed bin(31); /* Connection handle */
dcl SubDesc  like MQSD;     /* Subscription descriptor */
dcl Hobj     fixed bin(31); /* Object handle */
dcl Hsub     fixed bin(31); /* Subscription handle */
dcl CompCode fixed bin(31); /* Completion code */
dcl Reason   fixed bin(31); /* Reason code qualifying CompCode */

High Level Assembler 呼叫


CALL MQSUB,(HCONN,SUBDESC,HOBJ,HSUB,COMPCODE,REASON)
宣告參數如下:

HCONN    DS      F  Connection handle
SUBDESC  CMQSDA  ,  Subscription descriptor
HOBJ     DS      F  Object handle
HSUB     DS      F  Subscription handle
COMPCODE DS      F  Completion code
REASON   DS      F  Reason code qualifying COMPCODE