fteCreate代理程式 (建立 MFT 代理程式)

fteCreateAgent 指令會建立 Managed File Transfer Agent 及其相關聯的配置。

您可以控制代理程式的存取權。 如需進一步資訊，請參閱 限制 MFT 代理程式動作的使用者權限 。 您需要使用 -ac 參數，並提供存取部分佇列的權限。

重要事項: [UNIX、Linux、Windows]在 IBM® MQ for UNIX, Linux®, and Windows上，只有身為 IBM MQ 管理者 (及 mqm 群組成員) 的使用者才能執行此指令。 如果您嘗試以非 IBM MQ 管理者的使用者身分執行此指令，則會收到錯誤訊息BFGCL0502E: You are not authorized to perform the requested operation.，且指令將不會執行。
[z/OS]在 z/OS® 系統上，使用者必須滿足 (至少) 下列其中一個條件，才能執行移轉指令:
  • 是 mqm 群組的成員（如果 mqm 群組已定義在系統上）。
  • [2017 年 5 月 9.0.0.1 版]是 BFG_GROUP_NAME 環境變數所指名之群組的成員（如果已指名群組的話）。
  • [2017 年 5 月 9.0.0.1 版]指令執行時，BFG_GROUP_NAME 環境變數中未設定任何值。

用途

使用 fteCreateAgent 指令可建立代理程式。 此指令提供一些 MQSC 指令，必須針對代理程式佇列管理程式執行這些指令，才能建立下列代理程式佇列：
  • SYSTEM.FTE.AUTHADM1.agent_name
  • SYSTEM.FTE.AUTHAGT1.agent_name
  • SYSTEM.FTE.AUTHMON1.agent_name
  • SYSTEM.FTE.AUTHOPS1.agent_name
  • SYSTEM.FTE.AUTHSCH1.agent_name
  • SYSTEM.FTE.AUTHTRN1.agent_name
  • SYSTEM.FTE.COMMAND.agent_name
  • SYSTEM.FTE.DATA.agent_name
  • SYSTEM.FTE.EVENT.agent_name
  • SYSTEM.FTE.REPLY.agent_name
  • SYSTEM.FTE.STATE.agent_name
這些佇列是內部系統佇列，您不得從中修改、刪除或讀取訊息，除非您刪除代理程式。 下列位置的檔案也提供了要執行的 MQSC 指令：MQ_DATA_PATH\mqft\config\coordination_qmgr_name\agents\agent_name\agent_name_create.mqsc。

如果您稍後想要刪除代理程式，此指令也提供了您必須執行的 MQSC 指令，以清除並刪除代理程式使用的佇列。 MQSC 指令位於下列位置的檔案中: MQ_DATA_PATH\mqft\config\coordination_qmgr_name\agents\agent_name\agent_name_delete.mqsc。

Managed File Transfer 提供進階代理程式內容，可協助您配置代理程式。 這些內容在 agent.properties 檔案中說明。

您可能必須建立 MQMFTCredentials.xml 認證檔，才能使用您的代理程式。 此檔案的範例位於 MQ_INSTALLATION_PATH/mqft/samples/credentials/ 中。 如需相關資訊和範例，請參閱 MFT 認證檔案格式。

重要事項：

在 UNIX 平台及 Linux Managed File Transfer 指令上，使用 Socket 檔案與在相同主機上執行的代理程式處理程序進行通訊。

這些 Socket 檔案建立在代理程式的日誌目錄中，並在代理程式停止時刪除。 在 IBM MQ Managed File Transfer 安裝中，此 Socket 檔案是以下列檔案路徑建立: <MQ_DATA_PATH>/mqft/logs/<COORDINATION_QM_NAME>/agents/<AGENT_NAME>/logs/<AGENT_NAME>@<AGENT_QM_NAME> ，其中 MQ_DATA_PATH 依預設為 /var/mqm 。

若為可重新配送的代理程式，會在下列目錄下建立此 Socket 檔案: <RE_DISTRIBUTABLE_DIRECTORY>/mqft/logs/<COORDINATION_QM_NAME>/agents/<AGENT_NAME>/logs/<AGENT_NAME>@<AGENT_QM_NAME>。

例如，如果代理程式名稱為 SRCAGENT，代理程式佇列管理程式名稱為 SRCAGENTQM，協調佇列管理程式名稱為 COORDQM，且可重新配送的代理程式從目錄 /home/myuser/mqmft-redist執行，則此 Socket 檔案的完整路徑為: /home/myuser/mqmft-redist/mqft/logs/COORDQM/agents/SRCAGENT/logs/SRCAGENT@SRCAGENTQM

其檔案路徑長度總計為 85 個字元。

Socket 檔案的這些作業系統所容許的路徑長度上限為 107 個字元。 因此，在建立代理程式時，請小心確定 Socket 檔案路徑不超過 107 個字元。 這對於可重新配送的代理程式尤其重要，代理程式的日誌目錄可以位於任意目錄位置。 如需設定配置目錄的詳細資料，請參閱 fteCreateEnvironment 指令。

如果您啟動代理程式，或執行連接至代理程式的其他指令，且您的路徑長度超過 107 個字元，則會收到下列訊息:
BFGNV0159E: 嘗試連結至具有 FFDC 的 Socket 檔案失敗

特殊字元

如果使用的參數值包含特殊字元，請格外小心，以免指令 Shell 解譯字元的方式不符合預期。 例如，如果完整檔案路徑和名稱包含諸如空格、引號（單引號或雙引號）、正斜線或反斜線字元等字元，則可能會被指令 Shell 解譯，而不是直接傳遞至指令本身。 若要避免字元被指令 Shell 解譯，請用雙/單引號將整個參數括住，或者使用指令 Shell 的 ESC 序列來跳出特殊字元。

Syntax

fteCreateAgent

Read syntax diagramSkip visual syntax diagramfteCreateAgent-agentName agent_name -agentQMgr agent_qmgr_name -agentQMgrHost agent_qmgr_host-agentQMgrPort agent_qmgr_port-agentQMgrChannel agent_qmgr_channel-agentDesc agent_description-ac-authorityChecking-s service_name-su user_name -sp password-sj options-sl options -n-mquseriduserID-mqpasswordpassword-credentialsFilefilePath-p configuration_options -f

參數

-agentName (代理程式名稱)
必要項目。 要建立的代理程式的名稱。 代理程式名稱對其協調佇列管理程式必須是唯一的。

如需命名代理程式的相關資訊，請參閱 物件命名慣例。

-agentQMgr (代理程式佇列管理程式名稱)
必要項目。 代理程式佇列管理程式的名稱。
-agentQMgr主機 (agent_qmgr_host)
選用項目。 代理程式佇列管理程式的主機名稱或 IP 位址。

-agentQMgr埠 (agent_qmgr_port)
選用項目。 用戶端連接代理程式佇列管理程式所使用的埠號。

-agentQMgr通道 (agent_qmgr_channel)
選用項目。 用於連接至代理程式佇列管理程式的通道名稱。

-agentDesc (代理程式說明)
選用項目。 代理程式的說明，顯示在 IBM MQ Explorer中。

-ac 或 -authorityChecking
選用項目。 此參數會啟用權限檢查。 如果您指定此參數，代理程式會檢查是否已授權提交要求的使用者執行所要求的動作。 如需相關資訊，請參閱 限制 MFT 代理程式動作的使用者權限。

[Windows]-s (service_name)
選用（僅限於 Windows）。 指出代理程式以 Windows 服務方式執行，指令必須從 Windows 管理者使用者 ID 執行。 如果未指定 service_name，則此服務會命名為 mqmftAgentAGENTQMGR，其中 AGENT 是代理程式名稱，而 QMGR 是代理程式佇列管理程式名稱。

服務的顯示名稱 (顯示在「 Windows 服務 」視窗的 名稱 直欄中) 一律為 Managed File Transfer Agent AGENT@QMGR。

附註: 如果可重新配送的代理程式將以 Windows 服務方式執行，則需要在系統環境中設定 BFG_DATA 環境變數，服務才能運作。
[Windows]-su (user_name)
選用（僅限於 Windows）。 代理程式以 Windows 服務執行時，此參數會指定執行服務所使用的帳戶名稱。 若要使用 Windows 網域使用者帳戶來執行代理程式，請以 DomainName\UserName格式指定值。 若要使用本端內建網域中的帳戶執行服務，請以 UserName 格式指定值。

您使用 -su 參數指定的 Windows 使用者帳戶必須具有 Log on as a service 權限。 如需如何授與此權限的相關資訊，請參閱 以 Windows 服務方式執行 MFT 代理程式或日誌程式的指引。

指定 -s 時需要。

[Windows]-sp (password)
選用（僅限於 Windows）。

此參數僅在指定 -s 時有效。 如果在指定 -s 參數時不指定此參數，會產生一則警告訊息。 此訊息警告您，您必須先使用「Windows 服務」工具設定密碼，然後服務才能順利啟動。

[Windows]-sj (選項)
選用（僅限於 Windows）。 以 Windows 服務啟動代理程式時，以 -D 或 -X 的格式定義傳遞至 JVM 的選項清單。 這些選項會使用 # 記號或分號 (;) 字元來區隔。 如果您必須內含任何 # 或分號 (;) 字元，請將這些字元放在單引號內。

此參數僅在指定 -s 時有效。

[Windows]-sl (選項)
選用（僅限於 Windows）。 設定 Windows 服務日誌層次。 有效的選項是：error、info、warn、debug。 預設值是 info。 此選項在您發生 Windows 服務問題時會很有幫助。 將它設為 debug，可以在服務日誌檔中提供更詳細資訊。

此參數僅在指定 -s 時有效。

[Windows]-n
選用（僅限於 Windows）。 指示代理程式以正常程序執行。 此參數與 -s 選項互斥。 如果既不指定 -s 參數，也不指定 -n 參數，則代理程式會配置為正常 Windows 處理程序。

-p (configuration_options)
選用項目。 此參數會決定用於建立代理程式的配置選項集。 依照慣例，會使用非預設協調佇列管理程式的名稱作為此參數的輸入。 然後， fteCreateAgent 指令會使用與此非預設協調佇列管理程式相關聯的內容檔集。

只有在您想要使用不同於預設值的配置選項時，才需指定選用的 -p 參數。 如果未指定此參數，則會使用一組以預設協調佇列管理程式為基礎的配置選項。

-mquserid (userID)
選用項目。 指定用來向協調佇列管理程式進行鑑別的使用者 ID。
-mqpassword (password)
選用項目。 指定用來向協調佇列管理程式進行鑑別的密碼。 您還必須指定 -mquserid 參數。 如果指定了 -mquserid，卻未指定 -mqpassword，則系統會提示您提供相關聯的密碼。 將不會顯示密碼。
-credentialsFile (filePath)
選用項目。 現有或新認證檔的完整檔案路徑， IBM MQ 鑑別詳細資料會新增至其中。

此指令支援將一組 IBM MQ 鑑別詳細資料新增至具名 Managed File Transfer 認證檔。 當已啟用 IBM MQ 連線鑑別時，請使用這個指令。 如果更新現有的詳細資料，則必須使用 -f 強制參數。

-credentialPath (credentials_path)
此指令定義要將認證資訊移轉至的位置。 此參數可以是現有認證檔的目錄路徑，也可以是新認證檔的目錄路徑。 [z/OS]在 z/OS 平台上，認證檔可以是預先存在的分割資料集延伸 (PDSE)。 PDSE 可以包含現有成員，或認證檔的新成員。 必須更新 PDSE 的現有成員，以包含認證檔。 PDSE 的格式必須為分區塊變數。
-f
選用項目。 強制指令改寫不符合的現有參數。 指定此參數，並不會強制取代現有的 Windows 服務代理程式。

-? 或 -h
選用項目。 顯示指令語法。

範例

在此範例中，AGENT3 使用代理程式佇列管理程式 QM_NEPTUNE 建立，並使用預設協調佇列管理程式：

fteCreateAgent -agentName AGENT3 -agentQMgr QM_NEPTUNE
 -agentQMgrHost myhost.ibm.com -agentQMgrPort 1415 -agentQMgrChannel CHANNEL1

回覆碼

0
指令已順利完成。
1
指令未順利結束。