MQCONNX-連接佇列管理程式 (延伸)

MQCONNX 呼叫會將應用程式連接至佇列管理程式。它提供佇列管理程式連線控點，供應用程式在後續的 IBM® MQ 呼叫中使用。

MQCONNX 呼叫與 MQCONN 呼叫類似，但 MQCONNX 容許指定選項來控制呼叫的運作方式。

所有 IBM MQ 系統及連接至這些系統的 IBM MQ 用戶端都支援此呼叫。

無法在僅限伺服器安裝上建立用戶端連線，也無法在僅限用戶端安裝上建立本端連線。

語法

MQCONNX (QMgrName、 ConnectOpts、 Hconn、 CompCode、 Reason)

參數

QMgrName

類型: MQCHAR48 -輸入

如需詳細資料，請參閱 MQCONN-Connect 佇列管理程式中說明的 QMgrName 參數。

ConnectOpts

類型 :MQCNO-輸入/輸出

如需詳細資料，請參閱 MQCNO-Connect 選項。

赫科恩

類型 :MQHCONN-輸出

此控點代表佇列管理程式的連線。在應用程式發出的所有後續訊息佇列作業呼叫中指定它。當發出 MQDISC 呼叫時，或當定義控點範圍的處理單元終止時，它就不再有效。

IBM MQ 現在為 mqm 程式庫提供用戶端套件及伺服器套件。這表示當進行在 mqm 程式庫中找到的 MQI 呼叫時，會檢查連線類型以查看它是否為用戶端或伺服器連線，然後進行正確的基礎呼叫。因此，現在可以針對 mqm 程式庫鏈結傳遞 Hconn 的結束程式，但在用戶端安裝上使用。

控點範圍: 傳回的控點範圍取決於用來連接佇列管理程式的呼叫 (MQCONN 或 MQCONNX)。如果使用的呼叫是 MQCONNX ，則控點的範圍也取決於 MQCNO 結構的 Options 欄位中指定的 MQCNO_HANDLE_SHARE_ * 選項。

如果呼叫是 MQCONN ，或指定 MQCNO_HANDLE_SHARE_NONE 選項，則傳回的控點是 非共用 控點。
非共用控點的範圍是執行應用程式之平台所支援的最小平行處理單位 (如需詳細資料，請參閱表 1 ); 控點在發出呼叫的平行處理單位之外無效。
如果您指定 MQCNO_HANDLE_SHARE_BLOCK 或 MQCNO_HANDLE_SHARE_NO_BLOCK 選項，則傳回的控點是共用控點。
共用控點的範圍是擁有從中發出呼叫之執行緒的處理程序; 控點可以從屬於該處理程序的任何執行緒使用。並非所有平台都支援執行緒。
如果 MQCONN 或 MQCONNX 呼叫失敗，且完成碼等於 MQCC_FAILED ，則未定義 Hconn 值。

表 1. 各種平台上非共用控點的範圍
平台	非共用控點的範圍
z/OS®	CICS®: CICS 作業 IMS: 作業，直到下一個同步點 (排除作業的子作業) z/OS 批次和 TSO: 作業 (排除作業的子作業)
IBM i	工作
AIX® and Linux®	執行緒
32 位元 Windows 應用程式	執行緒
64 位元 Windows 應用程式	執行緒

在 z/OS for CICS 應用程式上，傳回的值為:

MQHC_DEF_HCONN: 預設連線控點。

CompCode

類型 :MQLONG-輸出

如需詳細資料，請參閱 MQCONN-Connect 佇列管理程式中說明的 CompCode 參數。

原因

類型 :MQLONG-輸出

下列代碼可以由 MQCONN 及 MQCONNX 呼叫傳回。如需 MQCONNX 呼叫可傳回的其他代碼清單，請參閱下列代碼。

如果 CompCode 是 MQCC_OK:

MQRC_NONE: (0 ， X'000 ') 沒有理由報告。

如果 CompCode 是 MQCC_WARNING:

MQRC_ALREADY_CONNECTED: (2002 ， X'7D2') 應用程式已連接。
MQRC_CLUSTER_EXIT_LOAD_ERROR: (2267 ， X'8DB') 無法載入叢集工作量結束程式。
MQRC_SSL_ALREADY_INITIALIZED: (2391 ， X' 957 ') SSL 已起始設定。

如果 CompCode 是 MQCC_FAILED:

MQRC_ADAPTER_CONN_LOAD_ERROR: (2129 ， X'851 ') 無法載入配接卡連線模組。
MQRC_ADAPTER_DEFS_ERROR: (2131 ， X'853 ') 配接卡子系統定義模組無效。
MQRC_ADAPTER_DEFS_LOAD_ERROR: (2132 ， X'854 ') 無法載入配接卡子系統定義模組。
MQRC_ADAPTER_NOT_AVAILABLE: (2204 ， X'89C') 配接卡無法使用。
MQRC_ADAPTER_SERV_LOAD_ERROR: (2130 ， X'852 ') 無法載入配接卡服務模組。
MQRC_ADAPTER_STORAGE_短缺: (2127 ， X'84F') 配接卡的儲存體不足。
MQRC_ANOTHER_Q_MGR_CONNECTED: (2103 ， X'837 ') 已連接另一個佇列管理程式。
MQRC_API_EXIT_ERROR: (2374 ， X' 946 ') API 結束程式失敗。
MQRC_API_EXIT_INIT_ERROR: (2375 ， X' 947 ') API 結束程式起始設定失敗。
MQRC_API_EXIT_TERM_ERROR: (2376 ， X' 948 ') API 結束程式終止失敗。
MQRC_ASDID_MISMATCH: (2157 ， X'86D') 主要和起始 ASID 不同。
MQRC_BUFFER_LENGTH_ERROR: (2005 ， X'7D5') 緩衝區長度參數無效。
MQRC_CALL_IN_PROGRESS: (2219 ， X'8AB') 在前一個呼叫完成之前輸入的 MQI 呼叫。
MQRC_CONN_ID_IN_USE: (2160 ， X'870 ') 連線 ID 已在使用中。
MQRC_CONNECTION_BROKEN: (2009 ， X'7D9') 與佇列管理程式的連線遺失。
MQRC_CONNECTION_ERROR: (2273 ， X'8E1') 處理 MQCONN 呼叫時發生錯誤。
MQRC_CONNECTION_NOT_AVAILABLE: (2568 ， X'A08') 當佇列管理程式無法在現行安裝上提供所要求連線類型的連線時，在 MQCONN 或 MQCONNX 呼叫中發生。無法僅在伺服器安裝上建立用戶端連線。無法僅在用戶端安裝上建立本端連線。
MQRC_CONNECTION_QUIESCING: (2202 ， X'89A') 連線靜止。
MQRC_CONNECTION_STOPPING: (2203 ， X'89B') 連線關閉。
MQRC_CRYPTO_HARDWARE_ERROR: (2382 ， X'94E') 加密硬體配置錯誤。
MQRC_DUPLICATE_RECOV_COORD: (2163 ， X'873 ') 回復協調程式存在。
MQRC_ENVIRONMENT_ERROR: (2012 ， X'7DC') 在環境中呼叫無效。
此外，在 MQCONNX 呼叫中，從 CICS 或 IMS 應用程式傳遞 MQCSP-安全參數控制區塊。
MQRC_HCONN_ERROR: (2018 ， X'7E2') 連線控點無效。
MQRC_HOST_NOT_AVAILABLE: (2538 ， X'9EA') 已從用戶端發出 MQCONN 呼叫來連接至佇列管理程式，但嘗試將交談配置給遠端系統失敗。
MQRC_INSTALLER_MISMATCH: (2583 ， X'A17') 佇列管理程式安裝與選取的程式庫之間不符。
MQRC_KEY_REPOSITORY_ERROR: (2381 ， X'94D') 金鑰儲存庫無效。
MQRC_MAX_CONNS_LIMIT_REACHED: (2025 ， X'7E9') 已達到連線數目上限。
MQRC_NOT_AUTHORIZED: (2035 ， X'7F3') 未獲授權存取。
MQRC_OPEN_FAILED: (2137 ， X'859 ') 物件未順利開啟。
MQRC_Q_MGR_NAME_ERROR: (2058 ， X'80A') 佇列管理程式名稱無效或不明。
MQRC_Q_MGR_NOT_AVAILABLE: (2059 ， X'80B') 佇列管理程式無法用於連線。
MQRC_Q_MGR_QUIESCING: (2161 ， X'871 ') 佇列管理程式靜止中。
MQRC_Q_MGR_STOPPING: (2162 ， X'872 ') 佇列管理程式關閉。
MQRC_RESOURCE_PROBLEM: (2102 ， X'836 ') 可用的系統資源不足。
MQRC_SECURITY_ERROR: (2063 ， X'80F') 發生安全錯誤。
MQRC_SSL_INITIALIZATION_ERROR: (2393 ， X' 959 ') SSL 起始設定錯誤。
MQRC_STORAGE_NOT_AVAILABLE: (2071 ， X'817 ') 可用的儲存體不足。
MQRC_UNEXPECTED_ERROR: (2195 ， X'893 ') 發生非預期的錯誤。

MQCONNX 呼叫可以傳回下列其他原因碼:

如果 CompCode 是 MQCC_FAILED:

MQRC_AIR_ERROR: (2385 ， X' 951 ') 鑑別資訊記錄無效。
MQRC_AUTH_INFO_CONN_NAME_ERROR: (2387 ， X' 953 ') 鑑別資訊連線名稱無效。
MQRC_AUTH_INFO_REC_COUNT_ERROR: (2383 ， X'94F') 鑑別資訊記錄計數無效。
MQRC_AUTH_INFO_REC_ERROR: (2384 ， X' 950 ') 鑑別資訊記錄欄位無效。
MQRC_AUTH_INFO_TYPE_ERROR: (2386 ， X' 952 ') 鑑別資訊類型無效。
MQRC_CD_ERROR: (2277 ， X'8E5') 通道定義無效。
MQRC_CLIENT_CONN_ERROR: (2278 ， X'8E6') 用戶端連線欄位無效。
MQRC_CNO_ERROR: (2139 ， X'85B') 連接選項結構無效。
MQRC_CONN_TAG_IN_USE: (2271 ， X'8DF') Connection 標籤使用中。
MQRC_CONN_TAG_NOT_USABLE: (2350 ， X'92E') 連線標籤無法使用。
MQRC_CSP_ERROR: (2595 ， X'A23') MQCSP 結構無效。
MQRC_FUNCTION_NOT_SUPPORTED: (2298 ， X'8FA') 在現行環境中無法使用所要求的功能。
MQRC_LDAP_PASSWORD_ERROR: (2390 ， X' 956 ') LDAP 密碼無效。
MQRC_LDAP_USER_NAME_ERROR: (2388 ， X' 954 ') LDAP 使用者名稱欄位無效。
MQRC_LDAP_USER_NAME_LENGTH_ERR: (2389 ， X' 955 ') LDAP 使用者名稱長度無效。
MQRC_OPTIONS_ERROR: (2046 ， X'7FE') 選項無效或不一致。
MQRC_SCO_ERROR: (2380 ， X'94C') SSL 配置選項結構無效。
MQRC_SSL_CONFIG_ERROR: (2392 ， X' 958 ') SSL 配置錯誤。
MQRC_TOKEN_TIMESTAMP_NOT_VALID: (2064、X'810 ') 鑑別記號尚未生效或已過期。

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

使用注意事項

對於 Visual Basic 程式設計語言，下列要點適用:

ConnectOpts 參數宣告為 MQCNO 類型。如果應用程式以 IBM MQ MQI client身分執行，且您想要指定用戶端連線通道的參數，請將 ConnectOpts 參數宣告為 Any類型，以便應用程式可以在呼叫上指定 MQCNOCD 結構來取代 MQCNO 結構。不過，這表示無法檢查 ConnectOpts 參數，以確定它是正確的資料類型。

C 呼叫


MQCONNX (QMgrName, &ConnectOpts, &Hconn, &CompCode, &Reason);

宣告參數如下:


MQCHAR48  QMgrName;     /* Name of queue manager */
MQCNO     ConnectOpts;  /* Options that control the action of MQCONNX */
MQHCONN   Hconn;        /* Connection handle */
MQLONG    CompCode;     /* Completion code */
MQLONG    Reason;       /* Reason code qualifying CompCode */

COBOL 呼叫


CALL 'MQCONNX' USING QMGRNAME, CONNECTOPTS, HCONN, COMPCODE,
REASON.

宣告參數如下:


**   Name of queue manager
 01  QMGRNAME     PIC X(48).
**   Options that control the action of MQCONNX
 01  CONNECTOPTS.
     COPY CMQCNOV.
**   Connection handle
 01  HCONN        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 MQCONNX (QMgrName, ConnectOpts, Hconn, CompCode, Reason);

宣告參數如下:


dcl QMgrName     char(48);       /* Name of queue manager */
dcl ConnectOpts  like MQCNO;     /* Options that control the action of
                                    MQCONNX */
dcl Hconn        fixed bin(31);  /* Connection handle */
dcl CompCode     fixed bin(31);  /* Completion code */
dcl Reason       fixed bin(31);  /* Reason code qualifying CompCode */

High Level Assembler 呼叫


CALL MQCONNX,(QMGRNAME,CONNECTOPTS,HCONN,COMPCODE,REASON)

宣告參數如下:


QMGRNAME     DS       CL48  Name of queue manager
CONNECTOPTS  CMQCNOA  ,     Options that control the action of MQCONNX
HCONN        DS       F     Connection handle
COMPCODE     DS       F     Completion code
REASON       DS       F     Reason code qualifying COMPCODE

Visual Basic 呼叫


MQCONNX QMgrName, ConnectOpts, Hconn, CompCode, Reason

宣告參數如下:


Dim QMgrName    As String*48 'Name of queue manager'
Dim ConnectOpts As MQCNO     'Options that control the action of'
                             'MQCONNX'
Dim Hconn       As Long      'Connection handle'
Dim CompCode    As Long      'Completion code'
Dim Reason      As Long      'Reason code qualifying CompCode'