配置 API 結束程式

API 結束程式是一個程式碼模組(.dll 檔),您可以自行提供,並緊接在 MQI 呼叫之前或之後執行。

關於此作業

IBM® MQ 接收到從程式到其 API 進入點之一的呼叫時,IBM MQ 會呼叫您的 API 結束程式。 API 結束程式會根據您配置結束程式的方式,在 MQI 執行之前或之後執行。

您可以配置要呼叫零個、一個或許多結束程式,也可以配置呼叫多個結束程式的順序。 在 WindowsLinux®(x86 和 x86-64 平台)上,您可以使用 IBM MQ Explorer 來配置 API 結束程式。 配置詳細資料會儲存在 .ini 檔中。

  1. IBM MQ Explorer 中配置 API 結束程式。
  2. 置換通用 API 結束程式,並使用本端 API 結束程式。
API 結束程式定義有三種類型:
共用 (ApiExitCommon)
每一部電腦一組定義。 當佇列管理程式啟動時,會讀取定義的 API 結束程式(如果有的話)並套用到佇列管理程式。 在 IBM MQ 內容對話框中配置共用 API 結束程式。 每一本端佇列管理程式之內容對話框中的「本端 API 結束程式」表格中。
範本 (ApiExitTemplate)
每一部電腦一組定義。 在建立佇列管理程式時,於這裡定義的 API 結束程式(如果有的話)會複製到新建立的佇列管理程式中作為本端結束程式。 在 IBM MQ 內容對話框中配置範本 API 結束程式。
本端 (ApiExitLocal)
每一佇列管理程式一組定義。 佇列管理程式啟動時,任何已定義的 API 結束程式會置換共用結束程式(如果兩者的名稱屬性相同,且已指定置換)。 置換共用 API 結束程式時,不論是否已指派選用的資料屬性值,都不會儲存共用定義中的任何欄位。 請在佇列管理程式的內容對話框中,配置本端 API 結束程式。
當您在 IBM MQ 及佇列管理程式內容對話框中配置 API 結束程式時,屬性值會新增至配置檔或 Windows 登錄中的 ApiExitCommonApiExitTemplateApiExitLocal 段落。
表 1. API 結束程式屬性
屬性 意義 段落索引鍵
姓名 指定 API 結束程式的說明性名稱,其會傳給 MQAXP 結構之 ExitInfoName 欄位中的 API 結束程式。 此名稱必須是唯一的,長度限制為 48 個字元,且必須只包含那些對 IBM MQ 物件名稱有效的字元,例如佇列名稱。 姓名
類型 指定結束程式的類型:commontemplatelocaloverride (不是個別的段落索引鍵。)
序列 這個屬性是不帶正負號的數值,其會定義呼叫這個 API 結束程式相較於其他 API 結束程式的順序。 具有低序號的 API 結束程式,會在另一個具有較高序號的 API 結束程式之前呼叫。 如果不同的 API 結束程式有相同的序號,其呼叫順序未定義。 在定義給佇列管理程式之 API 結束程式的序號中的跳號仍然有效。 序列
模組 指定含有 API 結束程式之程式碼的模組。 如果這個欄位含有模組的完整路徑名稱,則會依其現狀使用。 如果此欄位只包含模組名稱,則會使用與通道結束程式相同的方法來尋找模組; 亦即,使用佇列管理程式內容對話框 結束程式 頁面上 結束程式預設路徑 欄位中的值。 模組
函數 指定含有 API 結束程式的程式碼之模組內的函數進入點名稱。 這個進入點是 MQ_INIT_EXIT 函數。 這個欄位的長度限制為 MQ_EXIT_NAME_LENGTH。 函數
資料 如果指定這個屬性,系統會移除前端和尾端空白,其餘字串會截斷成 32 個字元,並將結果傳給 MQAXP 結構之 ExitData 欄位中的結束程式。 如果沒有指定這個屬性的話,會將預設值 32 個空格傳給 MQAXP 結構 ExitData 欄位中的結束程式。 資料

程序

  • [OPTION 1] 在 IBM MQ Explorer中配置 API 結束程式。
    1. 開啟相關的內容對話框:
    2. 在「 結束程式 」頁面上,按一下 新增 ...。 這時會開啟「新增 API 結束程式」對話框。
    3. 在「 新增 API 結束程式 」對話框的欄位中鍵入必要資訊。
    4. 按一下 確定 以建立結束程式,並關閉「 新增 API 結束程式 」對話框。
    新 API 結束程式的內容會顯示在「結束程式」頁面的表格中。
  • [OPTION 2] 將共用 API 結束程式置換為本端 API 結束程式。

    如果在佇列管理程式中定義的本端 API 結束程式與共用結束程式同名,則共用結束程式會被置換。 亦即,系統不會呼叫共用結束程式,而會改為呼叫置換的本端結束程式。 要避免不小心發生置換,使用者介面可讓您採取慎重的動作來配置置換作業;比方說,您不能以現有結束程式的相同名稱來新增結束程式,也不能將結束程式的名稱變更為與現有的結束程式相同。 不過,您可能要將本端 API 結束程式新增至佇列管理程式,才能不使用共用 API 結束程式而改用本端 API 結束程式。 在此情況下,您需要以本端 API 結束程式來置換共用 API 結束程式。

    1. 開啟佇列管理程式內容對話框的 結束程式 頁面。
    2. 本端 API 結束程式 表格中按一下您要置換的共用結束程式。
    3. 按一下 置換
      此時會開啟「編輯 API 結束程式」對話框,而且會顯示共用 API 結束程式的名稱。
    4. 在「 編輯 API 結束程式 」對話框中輸入本端 API 結束程式的詳細資料,然後按一下 確定 以儲存變更。
    這時本端結束程式會置換同名的共用結束程式。