Liberty for z/OS 上的最佳化本端配接器 API

有一組 z/OS® 原生語言可呼叫服務應用程式設計介面 (API) 和 Java™ EE 連接器架構 (JCA),支援 Liberty 上的 WebSphere® 最佳化本端配接器 (WOLA)。

您可以從下列原生程式設計語言,來使用可呼叫的服務:
  • Cobol
  • C/C++
  • PL/I
  • 高階組合語言

本端連線一詞是指針對 z/OS 系統上的外部位址空間與相同 z/OS 系統上的 Liberty 伺服器之間的通訊,所建立的跨記憶體鏈結。用戶端位址空間必須在相同 z/OS 映像檔上執行。配接器 API 在與每一個唯一登錄的呼叫端相關聯的儲存區中,管理這些本端連線。在每一個位址空間中,登錄名稱(12 個字元)只能用於其中的一組連線儲存區。單一位址空間中的唯一登錄數目,只受可用的儲存體量限制。

登錄

使用 BBOA1REG API,您可以向本端 Liberty 伺服器登錄。BBOA1REG API 要求將指向本端 Liberty 伺服器的最佳化連線群組,配置及登錄在指定的登錄名稱之下。

表 1. BBOA1REG API 語法
API 語法
BBOA1REG BBOA1REG (wolagroupnamepart1, wolagroupnamepart2, wolagroupnamepart3, registername, minconn, maxconn, registerflags, rc, rsn)
BBOA1REG API 接受下列輸入參數:
wolagroupnamepart1
為項目變數或項目常數,包含要加入之最佳化本端配接器群組名稱的第一部分。必須是以空值結尾且剛好 8 個字元的字串,並且必須透過參照傳遞。
wolagroupnamepart2
為項目變數或項目常數,包含要加入之最佳化本端配接器群組名稱的第二部分。必須是用空格填補且剛好 8 個字元的字串,並且必須透過參照傳遞。
wolagroupnamepart3
為項目變數或項目常數,包含要加入之最佳化本端配接器群組名稱的第三部分。必須是用空格填補且剛好 8 個字元的字串,並且必須透過參照傳遞。
registername(輸入)
為項目變數或項目常數,包含用來登錄一組本端連線的名稱。之後的呼叫需要這個名稱,來識別要使用的連線儲存區。這必須是一個用空格填補且剛好 12 個字元的字串,且無法供常駐程式群組中的另一個用戶端使用。如果這個用戶端連接至多個常駐程式群組,registername 只能在這個用戶端中使用一次。
minconn
整數,包含配置給這項登錄的起始連線數下限。在登錄期間,配接器會嘗試與相關聯的伺服器之間維持這個數目的連線。
重要: 即使 minconn 指定為 0,最基本會配置一條連線,來與目標伺服器連結,因此指定 0 與指定 1 相同。
maxconn
一個整數,包含配置給這項登錄的起始連線數上限。在「取得連線 API」要求期間,當最基本數目的連線都在使用中時,配接器會嘗試擴充本端連線儲存區到這個數目。
registerflags
包含登錄旗標的 32 位元旗標單字。
  • reg_flag_W2Cprop - 位元 31

    reg_flag_W2Cprop 旗標控制從 Liberty 伺服器至 CICS® 的出埠交易安全傳播。

  • reg_flag_C2Wprop - 位元 29

    reg_flat_C2Wprop 旗標會將呼叫端作業上的身分從 CICS 傳播到 Liberty 伺服器。若為來自 CICS 的入埠交易,旗標控制如何判斷身分。當開啟這個位元時,會在 Liberty 伺服器授權程序中使用 CICS 應用程式作業身分。當關閉這個位元時,會使用 CICS 區域身分。

  • reg_flag_trcmod - 位元 0

    如果您想修改所要求之登錄的最佳化本端配接器追蹤設定,請設定 reg_flag_trcmod 旗標。如果沒有設定這個旗標,則不會對追蹤設定進行任何變更,且會使用套用至登錄名稱或工作名稱的系統預設值或預先定義的追蹤設定。

  • reg_flag_trcmore - 位元 1,且 reg_flag_trcsome - 位元 2

    如果將 reg_flag_trcmod 旗標設為 1,您也必須指定登錄的追蹤層次,其作法是,設定 reg_flag_trcmore 旗標,表示詳細追蹤,或設定 reg_flag_trcsome 旗標,表示粗略層次的追蹤。如果將 reg_flag_trcmod 設為 1,當將 reg_flag_trcmore 旗標和 reg_flag_trcsome 旗標都設為 0 時,不論預先定義或預設值設為什麼,都會強制不對該項登錄執行任何追蹤。

BBOA1REG API 接受下列輸出參數:
rc
整數的回覆碼,指出這項呼叫成功或失敗。
rsn
整數的原因碼,說明這項呼叫失敗的原因。
使用注意事項:
  • 請確定您在這項呼叫中指定的 Liberty 伺服器已啟動,並且已啟用本端配接器支援。
  • 所要求的連線數下限會以伺服器連線數上限來驗證。連線數下限 (minconn) 值 3 表示登錄呼叫期間,會保留三條連線。如果在某個給定時間要求超過三條的連線,連線儲存區可以增加到連線數上限 (maxconn) 值。當指向伺服器的所有連線數目到達所允許的上限時,後續針對該伺服器所提出的所有「取得連線 API」要求都會遭到拒絕,即使尚未到達 maxconn 值也一樣。
    重要: 請謹慎設定連線數下限值。由於會針對每一條連線保留 Liberty 伺服器中的資源,除了特定實例,請勿設定太大的值。
  • 在相同的位址空間、執行緒或「客戶資訊控制系統 (CICS)」作業之下,可以多次呼叫「登錄 API」;不過,它們不能共用登錄名稱。 登錄名稱必須是唯一名稱。
  • 請使用「取消登錄 API」呼叫,來移除這項登錄,並釋放其相關聯的連線儲存區。
  • 當發出登錄呼叫的位址空間終止時,會自動終止登錄,並釋放連線。
回覆碼和原因碼:
表 2. BBOA1REG API 回覆碼和原因碼
回覆碼 原因碼 說明 動作
0 - 成功  
4 4 在配接器不支援廣域交易的環境中,交易式登錄旗標已設為 1。 忽略這項設定,並繼續執行處理程序。
8 - 錯誤 - 請參閱原因碼  
  8 該登錄名稱記號已存在。 在呼叫「登錄 API」之前,請先取消登錄這個名稱。
  12 指定的連線數下限參數大於上限。 請確定連線數下限設定小於或等於上限設定。
  14 嘗試建立登錄時,共用記憶體不足。 請增加最佳化本端配接器的共用記憶體配置,或是發出取消登錄呼叫,來減少資源耗用。
  74 輸入登錄名稱包含空值。 呼叫「登錄 API」之前,請先用空格填補登錄名稱,使名稱長度剛好是 12 個字元。
 

236

WOLA 名稱第 2 或 3 部分空白或遺漏。 請確定在 BBOA1REG 呼叫上,指定了 WOLA 名稱的第 2 或 3 部分。
 

480

用戶端無法成為獲授權呼叫登錄功能。 這是一個非預期的狀況。 請確定目標伺服器在執行中,且伺服器實例配置了 zosLocalAdapters 服務。
 

481

用戶端找不到 zosLocalAdapters 服務的授權功能表。 請確定在目標伺服器實例上配置了 zosLocalAdapters 特性。
12 10 API 找不到選取的最佳化本端配接器群組。 請確定 Liberty 伺服器和目標伺服器已啟動,並驗證最佳化本端配接器支援為作用中,然後再試一次。
  14 該使用者 ID 未獲授權使用所要求的 Liberty 伺服器。 請確定該使用者 ID 獲權使用所要求之 Liberty 伺服器的 CBIND SAF 類別。
  16 找不到最佳化本端配接器群組名稱的第二部分或第三部分。 請確定要傳遞的最佳化本端配接器群組名稱參數是有效的,且伺服器處於作用中。
  23 命名記號時發生錯誤。 請參閱 WebSphere Application Server 支援網站上的問題判斷資訊
  24 建立起始 Liberty 伺服器的本端通訊連線時發生錯誤。 請參閱 Liberty 伺服器區域日誌,取得本端通訊連線呼叫的詳細資料。
  28 以這個名稱識別的登錄無效。 指定的登錄名稱已登錄,但是遺漏登錄。暫行解決方法是呼叫「取消登錄 API」,然後重新嘗試呼叫「登錄 API」。如果問題仍在,請參閱 WebSphere Application Server 支援中心網站上的問題判斷資訊。
  68 連接至共用記憶體失敗。 請參閱 WebSphere Application Server 支援網站上的問題判斷資訊
  86 找不到 Liberty 伺服器的主要 BGVT。 Liberty 伺服器未在現行 z/OS 作業系統映像檔上啟動。在您啟動任何最佳化本端配接器用戶端程序之前,請確定伺服器已啟動。
  88 找不到 Liberty 伺服器的主要用戶端 Stub 表格。 Liberty 伺服器已在現行 z/OS 作業系統映像檔上啟動,但是伺服器不是在支援最佳化本端配接器用戶端 Stub 表格的層次執行。請確定與應用程式搭配執行的最佳化本端配接器 Stub 的層次,相容於這個 z/OS 系統上的 Liberty 伺服器。
  90 找不到 Liberty 伺服器最佳化本端配接器的主要用戶端 Stub 表格位置。 Liberty 伺服器已在現行 z/OS 作業系統映像檔上啟動,但是伺服器不是在支援最佳化本端配接器用戶端 Stub 表格的層次執行。請確定與應用程式搭配執行的最佳化本端配接器 Stub 的層次,相容於這個 z/OS 系統上的 Liberty 伺服器。
 

232

在登錄呼叫期間,發生記憶體不足狀況。 請確定在子儲存區 0 中,記憶體可供用戶端使用。重新嘗試 BBOA1REG 呼叫。
 

234

用戶端無法連結至 Liberty 伺服器實例。 請確定 Liberty 伺服器實例已啟動,且伺服器實例中已配置 zosLocalAdapters 服務。
 

238

用戶端無法找到目標伺服器的登錄。 這是一個非預期的狀況。 請確定目標伺服器實例已啟動,且已配置 zosLocalAdapters 特性。 如果伺服器已停止,請啟動它,然後重新嘗試 BBOA1REG 呼叫。

取消登錄

從本端的最佳化本端配接器群組和 Liberty 伺服器取消登錄,可使用 BBOA1URG API 來完成此動作。
表 3. BBOA1URG API 語法. 這個 API 要求使用指定的登錄名稱,釋放指向本端的最佳化本端配接器群組和 Liberty 伺服器的最佳化連線群組。
API 語法
BBOA1URG BBOA1URG (registername, unregflags, rc, rsn)
BBOA1URG API 接受下列輸入參數:
registername
為項目變數或項目常數,包含用來取消登錄一組本端連線的名稱。值必須剛好 12 個字元,用空格填補,並且是「登錄 API」呼叫上所使用的相同名稱。
unregisterflags
包含取消登錄旗標的 32 位元旗標單字。
  • Reserved - 位元 0-30
  • Force (0|1) - 位元 31

    指定 1,會強制執行取消登錄要求。依預設,只要所有連線都傳回到連線儲存區,取消登錄要求即告完成。如果沒有所有的連線都傳回到儲存區,會傳回警告給呼叫端。當最後一條連線傳回到儲存區,取消登錄程序即告完成。請發出第二個登錄要求,並將 force 位元設為 1,強制執行取消登錄程序,讓該項登錄的其餘所有連線控點都完成並失效。

BBOA1URG API接受下列輸出參數:
rc
整數的回覆碼,指出這項呼叫成功或失敗。
rsn
整數的原因碼,說明這項呼叫失敗的原因。
使用注意事項:
  • 請確定您在這項呼叫中指定的 Liberty 伺服器已啟動,並且已啟用本端配接器支援。
  • 如果沒有呼叫「取消登錄 API」,且發出登錄呼叫的位址空間終止,會自動完成取消登錄呼叫,並釋放連線。
  • 進行取消登錄呼叫期間,這項登錄的任何處於作用中的連線控點可能繼續維持有效,直到使用「釋放連線 API」將它們傳回到連線儲存區為止。如果要強制清除連線控點,必須發出第二項取消登錄呼叫,並指定 force 旗標。這會讓所有未完成的連線控點失效。
回覆碼和原因碼:
表 4. BBOA1URG API 回覆碼和原因碼
回覆碼 原因碼 說明 動作
0 - 成功  
4 - 警告 - 請參閱原因碼  
  66 取消登錄呼叫一直延遲到所有連線皆傳回到儲存區為止。 當最後一條連線傳回到可用儲存區時,取消登錄即告完成。
8 - 錯誤 - 請參閱原因碼  
  8 該登錄記號名稱不存在。 您必須先登錄這個名稱,再為它呼叫「取消登錄 API」。
  64 必須等發出正常的取消登錄之後,才能指定 force 選項。 請在呼叫「取消登錄 API」時,不要指定 force 選項。
  82 已嘗試取消登錄這項登錄。 請等待先前的取消登錄要求完成,或重新發出這項取消登錄,並使用 force 選項。
 

228

無法完成取消登錄呼叫,因為登錄已重複使用。 不需執行任何動作。
 

230

在取消登錄強制呼叫上,無法清除連線儲存區。 不需執行任何動作。如果要避免使用取消登錄強制呼叫,在呼叫取消登錄之前,請確定您的應用程式會將所有連線控點傳回儲存區。
 

480

用戶端無法成為獲授權呼叫取消登錄功能。 這是一個非預期的狀況。 請確定目標伺服器在執行中,且伺服器實例配置了 zosLocalAdapters 服務。
12 86 找不到 Liberty 伺服器的主要 BGVT。 Liberty 伺服器未在現行 z/OS 作業系統映像檔上啟動。在您啟動任何最佳化本端配接器用戶端程序之前,請確定伺服器已啟動。
  88 找不到 Liberty 伺服器的主要用戶端 Stub 表格。 Liberty 伺服器已在現行 z/OS 作業系統映像檔上啟動,但是伺服器不是在支援最佳化本端配接器用戶端 Stub 表格的層次執行。請確定與應用程式搭配執行的最佳化本端配接器 Stub 的層次,相容於這個 z/OS 系統上的 Liberty 伺服器。
  90 找不到 Liberty 伺服器最佳化本端配接器的主要用戶端 Stub 表格位置。 Liberty 伺服器已在現行 z/OS 作業系統映像檔上啟動,但是伺服器不是在支援最佳化本端配接器用戶端 Stub 表格的層次執行。請確定與應用程式搭配執行的最佳化本端配接器 Stub 的層次,相容於這個 z/OS 系統上的 Liberty 伺服器。

取得連線

這個 API 要求傳回儲存區中以選取的登錄名稱建立的可用連線。
表 5. BBOA1CNG API 語法
API 語法
BBOA1CNG BBOA1CNG (registername, connectionhandle, waittime, rc, rsn)
BBOA1CNG API 接受下列輸入參數:
registername
為項目變數或項目常數,包含用來尋找連線儲存區的名稱,以便從該連線儲存區擷取連線。這必須是一個用空格填補且剛好 12 個字元的字串。
connectionhandle
12 位元組連線控點,當之後要求對這條連線執行動作時,必須傳遞這個連線控點。
waittime
一個整數,含有在傳回「連線無法使用」原因碼之前,要等待連線完成的秒數。值 0 意指沒有等待時間,API 會無限期地等待。waittime 參數只適用於從連線儲存區取得 WOLA 連線的程序。取得的連線會用來接收伺服器的要求,且等待時間無限制。
BBOA1CNG API 接受下列輸出參數:
rc
整數的回覆碼,指出這項呼叫成功或失敗。
rsn
整數的原因碼,說明這項呼叫失敗的原因。
使用注意事項:
  • 請確定您在這項呼叫中指定的 Liberty 伺服器已啟動,並且已啟用本端配接器支援。
  • 在使用「取得連線 API」之前,請確定在具有相符名稱的現行位址空間中,「登錄 API」呼叫已順利完成。
回覆碼和原因碼:
表 6. BBOA1CNG API 回覆碼和原因碼
回覆碼 原因碼 說明 動作
0 - 成功  
4 - 警告 - 請參閱原因碼  
8 - 錯誤 - 請參閱原因碼  
  8 該登錄名稱記號不存在。 請先登錄這個名稱,再用「取得連線 API」呼叫這個名稱。
  10 連線無法使用。在可以取得連線要求之前,已過了等待時間。 應用程式行為是多樣的。請等待然後再試一次,或是發出異常終止巨集,來終止呼叫「取得連線 API」的作業。您也可以在「登錄 API」呼叫上增加連線數上限設定。
  24 登錄呼叫成功之後,從儲存區取得連線時發生錯誤。 請驗證伺服器已啟動。如果不在運作中,請重新啟動伺服器,然後重試 API 要求。
  28 找到登錄,但卻不在作用中。  
 

224

找到不完整的登錄。 這是一個非預期的狀況。 請利用 BBOA1URG 服務來取消登錄,然後利用 BBOA1REG 服務來重新登錄。
 

480

用戶端無法成為獲授權呼叫取得連線功能。 這是一個非預期的狀況。 請確定目標伺服器在執行中,且伺服器實例配置了 zosLocalAdapters 服務。
 

482

在伺服器重新啟動之後,用戶端無法重新連接至目標伺服器實例。 這是一個非預期的狀況。 請利用 BBOA1URG 服務來移除登錄,然後利用 BBOA1REG 服務來建立一個新的登錄。
 

483

在伺服器重新啟動之後,用戶端無法重新連接至目標伺服器實例。 這是一個非預期的狀況。 請利用 BBOA1URG 服務來移除登錄,然後利用 BBOA1REG 服務來建立一個新的登錄。
12 10 API 找不到選取的最佳化本端配接器群組。 請確定 Liberty 伺服器和目標伺服器已啟動,並驗證最佳化本端配接器支援為作用中,然後再試一次。
 

14

該使用者 ID 未獲授權使用所要求的 Liberty 伺服器。 請確定該使用者 ID 獲權使用所要求之 Liberty 伺服器的 CBIND SAF 類別。
  86 找不到 Liberty 伺服器的主要 BGVT。 Liberty 伺服器未在現行 z/OS 作業系統映像檔上啟動。在您啟動任何最佳化本端配接器用戶端程序之前,請確定伺服器已啟動。
  88 找不到 Liberty 伺服器的主要用戶端 Stub 表格。 Liberty 伺服器已在現行 z/OS 作業系統映像檔上啟動,但是伺服器不是在支援最佳化本端配接器用戶端 Stub 表格的層次執行。請確定與應用程式搭配執行的最佳化本端配接器 Stub 的層次,相容於這個 z/OS 系統上的 Liberty 伺服器。
  90 找不到 Liberty 伺服器最佳化本端配接器的主要用戶端 Stub 表格位置。 Liberty 伺服器已在現行 z/OS 作業系統映像檔上啟動,但是伺服器不是在支援最佳化本端配接器用戶端 Stub 表格的層次執行。請確定與應用程式搭配執行的最佳化本端配接器 Stub 的層次,相容於這個 z/OS 系統上的 Liberty 伺服器。

釋放連線

「釋放連線 API」要求將連線傳回到從中擷取的儲存區,讓另一個要求端可以使用它。
表 7. BBOA1CNR API 語法
API 語法
BBOA1CNR BBOA1CNR (connectionhandle, rc, rsn)
BBOA1CNR API 接受下列輸入參數:
connectionhandle
12 位元組連線控點,代表先前所取得而要釋放回連線儲存區的連線。
BBOA1CNR API 接受下列輸出參數:
rc
整數的回覆碼,指出這項呼叫成功或失敗。
rsn
整數的原因碼,說明這項呼叫失敗的原因。
使用注意事項
  • 請確定您在這項呼叫中指定的 Liberty 伺服器已啟動,並且已啟用本端配接器支援。
  • 在使用「釋放連線 API」之前,請確定在具有相符名稱的現行位址空間中,「登錄 API」呼叫已順利完成,並已順利完成「取得連線 API」而取得了現在要釋放的連線。
表 8. BBOA1CNR API 回覆碼和原因碼
回覆碼 原因碼 說明 動作
0 - 成功  
4 - 找不到最佳化本端配接器群組和 Liberty 伺服器。這條連線任何相關的資源都已清除。
8 - 錯誤 - 請參閱原因碼  
  36 連線狀態無效。 用於這項要求的連線控點處於錯誤狀態。請參閱 API 說明文件,取得連線狀態的規則。
  38 用戶端連線控點無效。 用於這項要求的用戶端連線控點無效。請參閱 API 說明文件,取得用戶端連線控點的相關資訊。
12 86 找不到 Liberty 伺服器的主要 BGVT。 Liberty 伺服器未在現行 z/OS 作業系統映像檔上啟動。在您啟動任何最佳化本端配接器用戶端程序之前,請確定伺服器已啟動。
  88 找不到 Liberty 伺服器的主要用戶端 Stub 表格。 Liberty 伺服器已在現行 z/OS 作業系統映像檔上啟動,但是伺服器不是在支援最佳化本端配接器用戶端 Stub 表格的層次執行。請確定與應用程式搭配執行的最佳化本端配接器 Stub 的層次,相容於這個 z/OS 系統上的 Liberty 伺服器。
  90 找不到 Liberty 伺服器最佳化本端配接器的主要用戶端 Stub 表格位置。 Liberty 伺服器已在現行 z/OS 作業系統映像檔上啟動,但是伺服器不是在支援最佳化本端配接器用戶端 Stub 表格的層次執行。請確定與應用程式搭配執行的最佳化本端配接器 Stub 的層次,相容於這個 z/OS 系統上的 Liberty 伺服器。

傳送要求

這些 API 會傳送要求給本端 Liberty 伺服器來進行處理。
表 9. BBOA1SRQ API 語法
API 語法
BBOA1SRQ BBOA1SRQ (connectionhandle, requesttype, requestservicename, requestservicenamel, requestdata, requestdatalen, async(0|1), responsedatalen, rc, rsn)
BBOA1SRQ API 接受下列輸入參數:
connectionhandle
12 位元組連線控點,用於這項要求。
requesttype
一個整數,所包含的要求類型指出要處理之工作要求的類型。唯一支援的值是 1,代表本端 EJB 工作要求。
requestservicename
EBCDIC 字串,長度最多 256 個位元組,包含要呼叫的服務名稱。這個參數指定本端商業介面的 JNDI 名稱。
requestservicenamel
整數,含有要啟動之服務名稱的長度,如果服務名稱以空值結尾,則為 0(零)。
requestdata
31 位元指標,指向要傳送之要求資料開頭的位址。
requestdatalen
32 位元不帶正負號的值 ,包含要傳送之資料的長度。
async(0|1)
async 設為 1,表示呼叫端希望立即傳回控制權,即使可能還不知道回應長度也一樣。如果將 async 設為 0,則現行執行緒會等待 Liberty 伺服器傳回回應,且 API 會在 responsedatalen 輸出參數中傳回回應長度。
BBOA1SRQ API 接受下列輸出參數:
responsedatalen
32 位元不帶正負號的值,包含回應的長度。呼叫端可以使用這個長度來獲得儲存體,然後您再呼叫「取得資料 API」,將資料複製到其中。當您將 async 設為 1,指出呼叫端希望立即傳回控制權時,如果尚未收到回應,會將值設為 0xFFFFFFFF
rc
整數的回覆碼,指出這項呼叫成功或失敗。
rsn
整數的原因碼,說明這項呼叫失敗的原因。
使用注意事項:
  • 請確定您在這項呼叫中指定的 Liberty 伺服器已啟動,並且已啟用本端配接器支援。
  • 在使用「傳送要求 API」之前,請確定在具有相符名稱的現行位址空間中,「登錄 API」呼叫已順利完成。
回覆碼和原因碼:
表 10. BBOA1SRQ API 回覆碼和原因碼
回覆碼 原因碼 說明 動作
0 - 成功  
4 - 警告 - 請參閱原因碼  
8 - 錯誤 - 請參閱原因碼  
  8 該登錄名稱記號已存在。 請確定所傳遞的登錄名稱是有效的。
  16 要求服務名稱的長度無效。 請更正程式,然後再試一次。
  18 要求長度超出系統限制。 訊息大小超過 Liberty 伺服器可支援的大小。請驗證大小是有效的。如果大小有效,請確定 Liberty 伺服器的大小足以容納訊息大小。
  32 API 呼叫要求類型無效。 要求類型無效。請更正程式,然後嘗試重新呼叫。
  34 找不到目標服務。 請確定包含目標 Enterprise Bean 的應用程式已安裝在 Liberty 伺服器的目標伺服器中,並且已啟動。
  36 連線狀態無效。 用於要求的連線控點處於錯誤狀態。請參閱 API 說明文件,取得連線狀態的規則。
  38 用戶端連線控點無效。 用於要求的用戶端連線控點無效。請參閱 API 說明文件,取得用戶端連線控點的相關資訊。
  40 發生本端通訊錯誤。 請檢查 Liberty 伺服器日誌,取得任何本端通訊錯誤訊息。
  44 目標 Enterprise Bean 中發生異常狀況或非預期的狀況。 請參閱 Liberty 伺服器日誌,以檢閱異常狀況資料。
  46 本端通訊傳送要求呼叫中發生錯誤。 請檢查 Liberty 伺服器日誌,以判斷錯誤。
  98 無法存取所提供之要求緩衝區的開頭。 請確定所提供的要求緩衝區位址和長度正確。
  100 無法存取所提供之要求緩衝區的結尾。 請確定所提供的要求緩衝區位址和長度正確。
12 10 API 找不到選取的最佳化本端配接器群組。 請確定 Liberty 伺服器和目標伺服器已啟動,並驗證最佳化本端配接器支援為作用中,然後再試一次。
  86 找不到 Liberty 伺服器的主要 BGVT。 Liberty 伺服器未在現行 z/OS 作業系統映像檔上啟動。在您啟動任何最佳化本端配接器用戶端程序之前,請確定伺服器已啟動。
  88 找不到 Liberty 伺服器的主要用戶端 Stub 表格。 Liberty 伺服器已在現行 z/OS 作業系統映像檔上啟動,但是伺服器不是在支援最佳化本端配接器用戶端 Stub 表格的層次執行。請確定與應用程式搭配執行的最佳化本端配接器 Stub 的層次,相容於這個 z/OS 系統上的 Liberty 伺服器。
  90 找不到 Liberty 伺服器最佳化本端配接器的主要用戶端 Stub 表格位置。 Liberty 伺服器已在現行 z/OS 作業系統映像檔上啟動,但是伺服器不是在支援最佳化本端配接器用戶端 Stub 表格的層次執行。請確定與應用程式搭配執行的最佳化本端配接器 Stub 的層次,相容於這個 z/OS 系統上的 Liberty 伺服器。

傳送回應

這個 API 會將要求的回應傳回給本端 Liberty 伺服器。
表 11. BBOA1SRP API 語法
API 語法
BBOA1SRP BBOA1SRP (connectionhandle, responsedata, responsedatalen, rc, rsn)
BBOA1SRP API 接受下列輸入參數:
connectionhandle
12 位元組連線控點,用於這項回應。
responsedata
31 位元指標,指向要傳送之回應資料開頭的位址。
requestdatalen
32 位元不帶正負號的值 ,包含要傳送之資料的長度。
BBOA1SRP API 接受下列輸出參數:
rc
整數的回覆碼,指出這項呼叫成功或失敗。
rsn
整數的原因碼,說明這項呼叫失敗的原因。
使用注意事項:
  • 請確定您在這項呼叫中指定的 Liberty 伺服器已啟動,並且已啟用本端配接器支援。
  • 在使用「傳送回應 API」之前,請確定在具有相符名稱的現行位址空間中,「登錄 API」呼叫已順利完成。
  • 請確定「取得連線 API」呼叫已順利完成,並在這項呼叫中以輸入形式提供控點。
  • 請確定已順利發出「接收要求(任何)API」、「接收要求(特定)API」或「主機 API」呼叫,且傳回了連線控點的要求資料。連線必須處於「傳送回應 API」被視為有效的狀態。
回覆碼和原因碼:
表 12. BBOA1SRP API 回覆碼和原因碼
回覆碼 原因碼 說明 動作
0 - 成功  
4 - 警告 - 請參閱原因碼  
8 - 錯誤 - 請參閱原因碼  
  8 該登錄名稱記號已存在。 請確定所傳遞的登錄名稱是有效的。
  18 要求長度超出系統限制。 訊息大小超過 Liberty 伺服器可支援的大小。請驗證大小是有效的。如果大小有效,請確定 Liberty 伺服器的大小足以容納訊息大小。
  34 找不到目標服務。 請確定包含目標 Enterprise Bean 的應用程式已安裝在 Liberty 伺服器的目標伺服器中,並且已啟動。
  36 連線狀態無效。 用於要求的連線控點處於錯誤狀態。請參閱 API 說明文件,取得連線狀態的規則。
  38 用戶端連線控點無效。 用於要求的用戶端連線控點無效。請參閱 API 說明文件,取得用戶端連線控點的相關資訊。
  40 發生本端通訊錯誤。 請檢查 Liberty 伺服器日誌,取得任何本端通訊錯誤訊息。
  46 本端通訊傳送要求呼叫中發生錯誤。 請檢查 Liberty 伺服器日誌,以判斷錯誤。
  102 無法存取所提供之回應緩衝區的開頭。 請確定所提供的回應緩衝區位址和長度正確。
  104 無法存取所提供之回應緩衝區的結尾。 請確定所提供的回應緩衝區位址和長度正確。
 

480

用戶端無法成為獲授權呼叫傳送回應功能。 這是一個非預期的狀況。 請確定目標伺服器在執行中,且伺服器實例配置了 zosLocalAdapters 服務。
12 10 API 找不到選取的最佳化本端配接器群組。 請確定 Liberty 伺服器和目標伺服器已啟動,並驗證最佳化本端配接器支援為作用中,然後再試一次。
  86 找不到 Liberty 伺服器的主要 BGVT。 Liberty 伺服器未在現行 z/OS 作業系統映像檔上啟動。在您啟動任何最佳化本端配接器用戶端程序之前,請確定伺服器已啟動。
  88 找不到 Liberty 伺服器的主要用戶端 Stub 表格。 Liberty 伺服器已在現行 z/OS 作業系統映像檔上啟動,但是伺服器不是在支援最佳化本端配接器用戶端 Stub 表格的層次執行。請確定與應用程式搭配執行的最佳化本端配接器 Stub 的層次,相容於這個 z/OS 系統上的 Liberty 伺服器。
  90 找不到 Liberty 伺服器最佳化本端配接器的主要用戶端 Stub 表格位置。 Liberty 伺服器已在現行 z/OS 作業系統映像檔上啟動,但是伺服器不是在支援最佳化本端配接器用戶端 Stub 表格的層次執行。請確定與應用程式搭配執行的最佳化本端配接器 Stub 的層次,相容於這個 z/OS 系統上的 Liberty 伺服器。

傳送回應異常狀況

這個 API 會傳送 ResourceException 異常狀況,其中含有傳回給本端 Liberty 伺服器中的 JCA 呼叫端的回應資料。

表 13. BBOA1SRX API 語法
API 語法
BBOA1SRX

BBOA1SRX (connectionhandle, excresponsedata, exresponsedatalen, rc, rsn)

BBOA1SRX API 接受下列輸入參數:
connectionhandle
12 位元組連線控點,用於這項回應。
excresponsedata
31 位元 指標,指向要傳送之異常狀況回應資料開頭的位址。
excresponsedatalen
32 位元不帶正負號的值,包含要傳送之異常狀況回應資料的長度。異常狀況回應資料是一個說明錯誤的 EBCDIC 字串。
BBOA1SRX API 接受下列輸出參數:
rc
整數的回覆碼,指出這項呼叫成功或失敗。
rsn
整數的原因碼,說明這項呼叫失敗的原因。
使用注意事項:
  • 請確定您在這項呼叫中指定的 Liberty 伺服器已啟動,並且已啟用本端配接器支援。
  • 在使用傳送回應呼叫之前,請確定在具有相符名稱的現行位址空間中,「登錄 API」呼叫已順利完成。
  • 請確定「取得連線 API」呼叫已順利完成,並在這項 API 呼叫中以輸入形式提供控點。
  • 請確定已順利發出「接收要求(任何)API」、「接收要求(特定)API」或「主機服務 API」呼叫,且傳回了連線控點的要求資料。連線必須處於「傳送回應 API」和「傳送回應異常狀況 API」被視為有效的狀態。
回覆碼和原因碼:
表 14. BBOA1SRX API 回覆碼和原因碼
回覆碼 原因碼 說明 動作
0 - 成功  
4 - 警告 - 請參閱原因碼  
8 - 錯誤 - 請參閱原因碼  
  8 該登錄名稱記號已存在。 請確定所傳遞的登錄名稱是有效的。
  10 連線控點處於已釋放或無效的狀態。 請確定所傳遞的連線控點是有效的。
  16 一或多個參數無效。 請驗證所有參數都是有效的,然後嘗試重新呼叫。
  18 要求長度超出系統限制。 訊息大小超過 Liberty 伺服器可支援的大小。請驗證大小是有效的。如果大小有效,請確定 Liberty 伺服器的大小足以容納訊息大小。
  36 連線狀態無效。 用於這項要求的連線控點處於錯誤狀態。請參閱 API 說明文件,取得連線狀態的規則。
  38 用戶端連線控點無效。 用於這項要求的用戶端連線控點無效。請參閱 API 說明文件,取得用戶端連線控點的相關資訊。
  40 發生本端通訊錯誤。 請檢查 Liberty 伺服器日誌,取得任何本端通訊錯誤訊息。
  46 本端通訊傳送要求呼叫中發生錯誤。 請檢查 Liberty 伺服器日誌,以判斷錯誤。
  102 無法存取所提供之回應緩衝區的開頭。 請確定所提供的回應緩衝區位址和長度正確。
  104 無法存取所提供之回應緩衝區的結尾。 請確定所提供的回應緩衝區位址和長度正確。
 

480

用戶端無法成為獲授權呼叫傳送異常狀況功能。 這是一個非預期的狀況。 請確定目標伺服器在執行中,且伺服器實例配置了 zosLocalAdapters 服務。
12 10 API 找不到選取的最佳化本端配接器群組。 請確定 Liberty 伺服器和目標伺服器已啟動,並驗證最佳化本端配接器支援為作用中,然後再試一次。
  86 找不到 Liberty 伺服器的主要 BGVT。 Liberty 伺服器未在現行 z/OS 作業系統映像檔上啟動。在您啟動任何最佳化本端配接器用戶端程序之前,請確定伺服器已啟動。
  88 找不到 Liberty 伺服器的主要用戶端 Stub 表格。 Liberty 伺服器已在現行 z/OS 作業系統映像檔上啟動,但是伺服器不是在支援最佳化本端配接器用戶端 Stub 表格的層次執行。請確定與應用程式搭配執行的最佳化本端配接器 Stub 的層次,相容於這個 z/OS 系統上的 Liberty 伺服器。
  90 找不到 Liberty 伺服器最佳化本端配接器的主要用戶端 Stub 表格位置。 Liberty 伺服器已在現行 z/OS 作業系統映像檔上啟動,但是伺服器不是在支援最佳化本端配接器用戶端 Stub 表格的層次執行。請確定與應用程式搭配執行的最佳化本端配接器 Stub 的層次,相容於這個 z/OS 系統上的 Liberty 伺服器。

接收要求(任何)

這個 API 會針對所傳遞的登錄名稱,接收來自儲存區中任何連線上的本端 Liberty 伺服器的要求和相關資料。 API 會以輸出參數形式傳回要求資料長度和連線控點。當使用傳回的連線控點來呼叫「取得資料 API」時,會傳回所接收的訊息資料。

表 15. BBOA1RCA API 語法
API 語法
BBOA1RCA BBOA1RCA (registername, connectionhandle, requestservicename, requestservicenamel, requestdatalen, waittime, rc, rsn)
BBOA1RCA API 接受下列輸入參數:
registername
為項目變數或項目常數,包含用來尋找連線儲存區的名稱,以便從該連線儲存區擷取連線。值必須是一個用空格填補且剛好 12 個字元的字串。
waittime
一個整數,含有在傳回「連線無法使用」原因碼之前,要等待連線完成的秒數。值 0 表示沒有等待時間,API 會無限期地等待。waittime 參數只適用於從連線儲存區取得 WOLA 連線的程序。取得的連線會用來接收伺服器的要求,且等待時間無限制。
BBOA1RCA API 接受下列輸入或輸出參數:
requestservicename
EBCDIC 字串,長度最多 256 個位元組,包含服務的名稱。這個參數是 Liberty 伺服器應用程式在 InteractionSpec 介面中指定的目標服務名稱。值 * 表示在現行登錄名稱之下送達之所有服務名稱的接收要求。
requestservicenamel
一個整數,含有要啟動之服務名稱的長度,如果服務名稱以空值結尾,則為 0
BBOA1RCA API 接受下列輸出參數:
connectionhandle
所傳回的 12 位元組連線控點,當之後要求對這條連線執行動作時,必須傳遞這個連線控點。
requestdatalen
32 位元不帶正負號的值,會傳回要接收的資料長度。
rc
整數的回覆碼,指出這項呼叫成功或失敗。
rsn
整數的原因碼,說明這項呼叫失敗的原因。
使用注意事項:
  • 請確定您在這項呼叫中指定的 Liberty 伺服器已啟動,並且已啟用本端配接器支援。
  • 在使用「登錄 API」之前,請確定在具有相符名稱的現行位址空間中,該 API 呼叫已順利完成。
回覆碼和原因碼:
表 16. BBOA1RCA API 回覆碼和原因碼
回覆碼 原因碼 說明 動作
0 - 成功  
4 - 警告 - 請參閱原因碼  
8 - 錯誤 - 請參閱原因碼  
  8 該登錄名稱記號已存在。 請確定所傳遞的登錄名稱是有效的。
  10 連線無法使用。在可以取得連線要求之前,已過了等待時間。 應用程式行為是多樣的。請等待然後再試一次,或是發出異常終止巨集,來終止呼叫「取得連線 API」的作業。您也可以在「登錄 API」呼叫上增加連線數上限設定。
  16 要求服務名稱的長度無效。 請更正程式,然後嘗試重新呼叫。
  19 呼叫本端通訊服務時,收到非零的回覆碼。  
  21 呼叫本端通訊服務時,收到非零的回覆碼。  
  38 用戶端連線控點無效。 用於這項要求的用戶端連線控點被判定無效。請參閱 API 說明文件,取得用戶端連線控點的相關資訊。
  40 發生本端通訊錯誤。 請檢查 Liberty 伺服器日誌,取得任何本端通訊錯誤訊息。
  46 本端通訊傳送要求呼叫中發生錯誤。 請檢查 Liberty 伺服器日誌,以判斷錯誤。
 

224

找到不完整的登錄。 這是一個非預期的狀況。 請利用 BBOA1URG 服務來取消登錄,然後利用 BBOA1REG 服務來重新登錄。
 

226

找到不完整的連線控點。 這是一個非預期的狀況。 請利用 BBOA1RCA 服務來重新嘗試要求。
 

480

用戶端無法成為獲授權呼叫接收要求功能。 這是一個非預期的狀況。 請確定目標伺服器在執行中,且伺服器實例配置了 zosLocalAdapters 服務。
 

482

在伺服器重新啟動之後,用戶端無法重新連接至目標伺服器實例。 這是一個非預期的狀況。 請利用 BBOA1URG 服務來移除登錄,然後利用 BBOA1REG 服務來建立一個新的登錄。
 

483

在伺服器重新啟動之後,用戶端無法重新連接至目標伺服器實例。 這是一個非預期的狀況。 請利用 BBOA1URG 服務來移除登錄,然後利用 BBOA1REG 服務來建立一個新的登錄。
12 10 API 找不到選取的最佳化本端配接器群組。 請確定 Liberty 伺服器和目標伺服器已啟動,並驗證最佳化本端配接器支援為作用中,然後再試一次。
 

14

該使用者 ID 未獲授權使用所要求的 Liberty 伺服器。 請確定該使用者 ID 獲權使用所要求之 Liberty 伺服器的 CBIND SAF 類別。
  24 登錄呼叫成功之後,從儲存區取得連線時發生錯誤。 請驗證伺服器已啟動。如果伺服器未啟動,請重新啟動伺服器,然後重試 API 要求。
  86 找不到 Liberty 伺服器的主要 BGVT。 Liberty 伺服器未在現行 z/OS 作業系統映像檔上啟動。在您啟動任何最佳化本端配接器用戶端程序之前,請確定伺服器已啟動。
  88 找不到 Liberty 伺服器的主要用戶端 Stub 表格。 Liberty 伺服器已在現行 z/OS 作業系統映像檔上啟動,但是伺服器不是在支援最佳化本端配接器用戶端 Stub 表格的層次執行。請確定與應用程式搭配執行的最佳化本端配接器 Stub 的層次,相容於這個 z/OS 系統上的 Liberty 伺服器。
  90 找不到 Liberty 伺服器最佳化本端配接器的主要用戶端 Stub 表格位置。 Liberty 伺服器已在現行 z/OS 作業系統映像檔上啟動,但是伺服器不是在支援最佳化本端配接器用戶端 Stub 表格的層次執行。請確定與應用程式搭配執行的最佳化本端配接器 Stub 的層次,相容於這個 z/OS 系統上的 Liberty 伺服器。

接收要求(特定)

這個 API 會針對指定的連線控點,接收來自本端 Liberty 伺服器的要求和相關資料。API 會以輸出參數形式傳回要求資料長度。當使用指定的連線控點來呼叫「取得資料 API」時,會傳回所接收的訊息資料。
表 17. BBOA1RCS API 語法
API 語法
BBOA1RCS BBOA1RCS (connectionhandle, requestservicename, requestservicenamel, requestdatalen, async(0|1), rc, rsn)
BBOA1RCS API 接受下列輸入參數:
connectionhandle
12 位元組連線控點,用於接收要求。
async(0|1)
async 設為 1,表示呼叫端希望立即傳回控制權,即使可能還不知道回應長度也一樣。如果您將 async 設為 0,這項呼叫會等待接收來自 Liberty 伺服器的要求。
BBOA1RCS API 接受下列輸入或輸出參數:
requestservicename
EBCDIC 字串,長度最多 256 個位元組,包含服務的名稱。這個參數是 Liberty 伺服器應用程式在 InteractionSpec 介面中指定的目標服務名稱。值 * 表示設定為在現行登錄名稱之下送達之所有服務名稱的伺服器。
requestservicenamel
一個整數,含有要啟動之服務名稱的長度,如果服務名稱以空值結尾,則為 0
BBOA1RCS API 接受下列輸出參數:
requestdatalen
32 位元不帶正負號的值所傳回的 32 位元不帶正負號的值,含有所接收之要求資料的長度。之後呼叫端可以使用這個長度來獲得儲存體,然後您再呼叫「取得資料 API」,將資料複製到其中。當 async 設為 1,指出呼叫端希望立即傳回控制權時,如果尚未收到要求資料,會將值設為 0xFFFFFFFF。在這種情況下,您必須重新呼叫 API,以擷取入埠要求。
rc
整數的回覆碼,指出這項呼叫成功或失敗。
rsn
整數的原因碼,說明這項呼叫失敗的原因。
使用注意事項:
  • 請確定您在這項呼叫中指定的 Liberty 伺服器已啟動,並且已啟用本端配接器支援。
  • 在使用「登錄 API」之前,請確定在具有相符名稱的現行位址空間中,該 API 呼叫已順利完成。
回覆碼和原因碼:
表 18. BBOA1RCS API 回覆碼和原因碼
回覆碼 原因碼 說明 動作
0 - 成功  
4 - 警告 - 請參閱原因碼  
8 - 錯誤 - 請參閱原因碼  
  8 該登錄名稱記號已存在。 請確定所傳遞的登錄名稱是有效的。
  10 連線控點處於已釋放或不適當的狀態。 請確定所傳遞的連線控點是有效的。
  16 要求服務名稱的長度無效。 請更正程式,然後嘗試重新呼叫。
  19 呼叫本端通訊服務時,收到非零的回覆碼。  
  21 呼叫本端通訊服務時,收到非零的回覆碼。  
  36 連線狀態無效。 用於這項要求的連線控點處於錯誤狀態。請參閱 API 說明文件,取得連線狀態的規則。
  38 用戶端連線控點無效。 用於這項要求的用戶端連線控點無效。請參閱 API 說明文件,取得用戶端連線控點的相關資訊。
  40 發生本端通訊錯誤。 請檢查 Liberty 伺服器日誌,取得任何本端通訊錯誤訊息。
  46 本端通訊傳送要求呼叫中發生錯誤。 請檢查 Liberty 伺服器日誌,以判斷錯誤。
  76 嘗試與伺服器通訊失敗,因為伺服器不再執行。 請啟動伺服器,並嘗試重新通訊。
  78 發生內部錯誤,導致連線選取的要求不是這條連線要處理之交易的一部分。 請將連線傳回到連線儲存區。如果問題仍在,請參閱 WebSphere Application Server 支援中心網站上的問題判斷資訊。
  80 這條連線上的作用中交易發生逾時,且無法重設連線狀態,因此改處理另一項要求。 請將連線傳回到連線儲存區。如果問題仍在,請參閱 WebSphere Application Server 支援中心網站上的問題判斷資訊。
 

226

找到不完整的連線控點。 這是一個非預期的狀況。 請利用 BBOA1CNR 服務來釋放連線,然後利用 BBOA1CNG 服務來取得新的連線。
 

480

用戶端無法成為獲授權呼叫接收要求功能。 這是一個非預期的狀況。 請確定目標伺服器在執行中,且伺服器實例配置了 zosLocalAdapters 服務。
12 10 API 找不到選取的最佳化本端配接器群組。 請確定 Liberty 伺服器和目標伺服器已啟動,並驗證最佳化本端配接器支援為作用中,然後再試一次。
  86 找不到 Liberty 伺服器的主要 BGVT。 Liberty 伺服器未在現行 z/OS 作業系統映像檔上啟動。在您啟動任何最佳化本端配接器用戶端程序之前,請確定伺服器已啟動。
  88 找不到 Liberty 伺服器的主要用戶端 Stub 表格。 Liberty 伺服器已在現行 z/OS 作業系統映像檔上啟動,但是伺服器不是在支援最佳化本端配接器用戶端 Stub 表格的層次執行。請確定與應用程式搭配執行的最佳化本端配接器 Stub 的層次,相容於這個 z/OS 系統上的 Liberty 伺服器。
  90 找不到 Liberty 伺服器最佳化本端配接器的主要用戶端 Stub 表格位置。 Liberty 伺服器已在現行 z/OS 作業系統映像檔上啟動,但是伺服器不是在支援最佳化本端配接器用戶端 Stub 表格的層次執行。請確定與應用程式搭配執行的最佳化本端配接器 Stub 的層次,相容於這個 z/OS 系統上的 Liberty 伺服器。

接收回應長度

「接收回應長度 API」會從先前的「傳送要求」呼叫,擷取回應資料的長度。
表 19. BBOA1RCL API 語法
API 語法
BBOA1RCL BBOA1RCL (connectionhandle, async(0|1), responsedatalen, rc, rsn)
BBOA1RCL API 接受下列輸入參數:
connectionhandle
12 位元組連線控點,用於這項要求。
async(0|1)
async 設為 1,表示呼叫端希望立即傳回控制權,即使可能不知道回應長度也一樣。如果將 async 設為 0,則這項呼叫會等待 Liberty 伺服器傳回回應,且 API 會在 responsedatalen 參數中傳回回應長度。
BBOA1RCL API 接受下列輸出參數:
requestdatalen
32 位元不帶正負號的值,會傳回所接收資料的長度。呼叫端可以使用這個長度來獲得儲存體,然後您再呼叫「取得資料 API」,將資料複製到其中。如果您將 async 設為 1,而且尚未收到回應資料,則會將值設為 0xFFFFFFFF
rc
整數的回覆碼,指出這項呼叫成功或失敗。
rsn
整數的原因碼,說明這項呼叫失敗的原因。
使用注意事項:
  • 請確定您在這項呼叫中指定的 Liberty 伺服器已啟動,並且已啟用本端配接器支援。
  • 在使用「登錄 API」之前,請確定在具有相符名稱的現行位址空間中,該 API 呼叫已順利完成。
  • 請確定「取得連線 API」呼叫已順利完成,並在這項呼叫中以輸入形式提供控點。
  • 發出「傳送要求 API」呼叫之前,請確定這項呼叫已順利完成。
回覆碼和原因碼:
表 20. BBOA1RCL API 回覆碼和原因碼
回覆碼 原因碼 說明 動作
0 - 成功  
4 - 警告 - 請參閱原因碼  
8 - 錯誤 - 請參閱原因碼  
  8 該登錄名稱記號已存在。 請確定所傳遞的登錄名稱是有效的。
  19 呼叫本端通訊服務時,收到非零的回覆碼。  
  21 呼叫本端通訊服務時,收到非零的回覆碼。  
  36 連線狀態無效。 用於這項要求的連線控點被判定處於錯誤狀態。請參閱 API 說明文件,取得連線狀態的規則。
  38 用戶端連線控點無效。 用於這項要求的用戶端連線控點被判定無效。請參閱 API 說明文件,取得用戶端連線控點的相關資訊。
  40 發生本端通訊錯誤。 請檢查 Liberty 伺服器日誌,取得任何本端通訊錯誤訊息。
 

226

找到不完整的連線控點。 這是一個非預期的狀況。 請利用 BBOA1CNR 服務來釋放連線,然後利用 BBOA1CNG 服務來取得新的連線。
 

480

用戶端無法成為獲授權呼叫接收長度功能。 這是一個非預期的狀況。 請確定目標伺服器在執行中,且伺服器實例配置了 zosLocalAdapters 服務。
12 10 API 找不到選取的最佳化本端配接器群組。 請確定 Liberty 伺服器和目標伺服器已啟動,並驗證最佳化本端配接器支援為作用中,然後再試一次。
  86 找不到 Liberty 伺服器的主要 BGVT。 Liberty 伺服器未在現行 z/OS 作業系統映像檔上啟動。在您啟動任何最佳化本端配接器用戶端程序之前,請確定伺服器已啟動。
  88 找不到 Liberty 伺服器的主要用戶端 Stub 表格。 Liberty 伺服器已在現行 z/OS 作業系統映像檔上啟動,但是伺服器不是在支援最佳化本端配接器用戶端 Stub 表格的層次執行。請確定與應用程式搭配執行的最佳化本端配接器 Stub 的層次,相容於這個 z/OS 系統上的 Liberty 伺服器。
  90 找不到 Liberty 伺服器最佳化本端配接器的主要用戶端 Stub 表格位置。 Liberty 伺服器已在現行 z/OS 作業系統映像檔上啟動,但是伺服器不是在支援最佳化本端配接器用戶端 Stub 表格的層次執行。請確定與應用程式搭配執行的最佳化本端配接器 Stub 的層次,相容於這個 z/OS 系統上的 Liberty 伺服器。

取得訊息資料

這個 API 會複製所接收的訊息資料。當這項 API 呼叫傳回時,會將訊息從配接器訊息快取中移除。
表 21. BBOA1GET API 語法
API 語法
BBOA1GET BBOA1GET (connectionhandle, msgdata, msgdatalen, rc, rsn, rv)
BBOA1GET API 接受下列輸入參數:
connectionhandle
12 位元組連線控點,用於這項要求。
msgdata
31 位元指標,指向要複製到其中的資料區域開頭的位址。這個參數指向的儲存體,必須位於呼叫端可以寫入的索引鍵中。
msgdatalen
32 位元不帶正負號的值,包含要複製之資料的長度。
BBOA1GET API 接受下列輸出參數:
rc
整數的回覆碼,指出這項呼叫成功或失敗。
rsn
整數的原因碼,說明這項呼叫失敗的原因。
rv
32 位元整數回覆值,含有這項要求的環境定義緩衝區大小。
使用注意事項:
  • 請確定您在這項呼叫中指定的 Liberty 伺服器已啟動,並且已啟用本端配接器支援。
  • 在使用「傳送要求 API」之前,請確定在具有相符名稱的現行位址空間中,「登錄 API」呼叫已順利完成。
  • 請確定「取得連線 API」呼叫已順利完成,並在這項呼叫中以輸入形式提供控點。
  • 如果 API 呼叫端輸入的 msgdatalen 參數大於實際訊息回應,回覆碼包含 0,且會提供實際訊息長度給回覆值。
  • 重要: 在「取得訊息資料」呼叫傳回給呼叫端之後,訊息資料不會持續保存,且連線會回到一個可用於另一項傳送或接收要求呼叫的狀態。當後續呼叫「取得訊息資料」或「接收回應長度」時,會在錯誤狀態下傳回。
回覆碼和原因碼:
表 22. BBOA1GET API 回覆碼和原因碼
回覆碼 原因碼 說明 動作
0 - 成功  
4 - 警告 - 請參閱原因碼  
8 - 錯誤 - 請參閱原因碼  
  8 該登錄名稱記號已存在。 請確定所傳遞的登錄名稱是有效的。
  36 連線狀態無效。 用於這項要求的連線控點被判定處於錯誤狀態。請參閱 API 說明文件,取得連線狀態的規則。
  38 用戶端連線控點無效。 用於這項要求的用戶端連線控點被判定無效。請參閱 API 說明文件,取得用戶端連線控點的相關資訊。
  40 發生本端通訊錯誤。 請檢查 Liberty 伺服器日誌,取得任何本端通訊錯誤訊息。
  48 本端通訊讀取要求中發生錯誤。 請檢查 Liberty 伺服器日誌,以判斷錯誤。
  72 回應長度的輸入參數不夠大,無法包含回應訊息。 只會傳回訊息的一部分。其餘部分會捨棄。請參閱回覆值,取得訊息回應的大小。
  98 無法存取所提供之要求緩衝區的開頭。 請確定所提供的要求緩衝區位址和長度正確。
  100 無法存取所提供之要求緩衝區的結尾。 請確定所提供的要求緩衝區位址和長度正確。
  102 無法存取所提供之回應緩衝區的開頭。 請確定所提供的回應緩衝區位址和長度正確。
  104 無法存取所提供之回應緩衝區的結尾。 請確定所提供的回應緩衝區位址和長度正確。
 

226

找到不完整的連線控點。 這是一個非預期的狀況。 請利用 BBOA1CNR 服務來釋放連線,然後利用 BBOA1CNG 服務來取得新的連線。
 

480

用戶端無法成為獲授權呼叫取得資料功能。 這是一個非預期的狀況。 請確定目標伺服器在執行中,且伺服器實例配置了 zosLocalAdapters 服務。
12 10 API 找不到選取的最佳化本端配接器群組。 請確定 Liberty 伺服器和目標伺服器已啟動,並驗證最佳化本端配接器支援為作用中,然後再試一次。
  86 找不到 Liberty 伺服器的主要 BGVT。 Liberty 伺服器未在現行 z/OS 作業系統映像檔上啟動。在您啟動任何最佳化本端配接器用戶端程序之前,請確定伺服器已啟動。
  88 找不到 Liberty 伺服器的主要用戶端 Stub 表格。 Liberty 伺服器已在現行 z/OS 作業系統映像檔上啟動,但是伺服器不是在支援最佳化本端配接器用戶端 Stub 表格的層次執行。請確定與應用程式搭配執行的最佳化本端配接器 Stub 的層次,相容於這個 z/OS 系統上的 Liberty 伺服器。
  90 找不到 Liberty 伺服器最佳化本端配接器的主要用戶端 Stub 表格位置。 Liberty 伺服器已在現行 z/OS 作業系統映像檔上啟動,但是伺服器不是在支援最佳化本端配接器用戶端 Stub 表格的層次執行。請確定與應用程式搭配執行的最佳化本端配接器 Stub 的層次,相容於這個 z/OS 系統上的 Liberty 伺服器。

呼叫

這個 API 會使用其他的基礎 API 基本函數,來呼叫本端 Liberty 伺服器中的方法。依照其設計,是在已預先知道回應輸出區域大小上限的情況下使用。
表 23. BBOA1INV API 語法
API 語法
BBOA1INV BBOA1INV (registername, requesttype, requestservicename, requestservicenamel, requestdata, requestdatalen, responsedata, responsedatalen, waittime, rc, rsn, rv)
BBOA1INV API 接受下列輸入參數:
registername
為項目變數或項目常數,包含用來尋找連線儲存區的名稱,以便擷取連線來進行這項呼叫。值必須是一個用空格填補且剛好 12 個字元的字串。
requesttype
一個整數,包含要求類型,指出要處理之工作要求的類型。唯一支援的值是 1,代表本端 EJB 工作要求。
requestservicename
EBCDIC 字串,長度最多 256 個位元組,包含要呼叫的服務名稱。這個參數指定本端商業介面的 JNDI 名稱。
requestservicenamel
一個整數,含有要啟動之服務名稱的長度,如果服務名稱以空值結尾,則為 0
requestdata
31 位元指標,指向要傳送之要求資料開頭的位址。
requestdatalen
32 位元不帶正負號的值 ,包含要傳送之要求資料的長度。
responsedata
31 位元指標,指向要複製到其中的回應資料區域開頭的位址。這個參數指向的儲存體,必須位於呼叫端可以寫入的索引鍵中。
responsedatalen
32 位元不帶正負號的值,包含要傳送之回應資料的長度。
waittime
一個整數,含有在傳回「連線無法使用」原因碼之前,要等待連線完成的秒數。值 0(零)表示沒有逾時,且這個 API 會無限期地等待。waittime 參數只適用於從連線儲存區取得 WOLA 連線的程序。取得的連線會用來接收伺服器的要求,且等待時間無限制。
BBOA1INV API 接受下列輸出參數:
rc
整數的回覆碼,指出這項呼叫成功或失敗。
rsn
整數的原因碼,說明這項呼叫失敗的原因。
rv
32 位元整數回覆值,含有已接收並複製到呼叫端回應區域的訊息資料的大小。
使用注意事項:
  • 請確定您在這項呼叫中指定的 Liberty 伺服器已啟動,並且已啟用本端配接器支援。
  • 在使用「傳送要求 API」之前,請確定在具有相符名稱的現行位址空間中,「登錄 API」呼叫已順利完成。
  • 如果 API 呼叫端輸入的 responsedatalen 參數大於實際訊息回應,回覆碼會包含 0(零),且會在回覆值中提供實際訊息長度。
回覆碼和原因碼:
表 24. BBOA1INV API 回覆碼和原因碼
回覆碼 原因碼 說明 動作
0 - 成功  
4 - 警告 - 請參閱原因碼  
8 - 錯誤 - 請參閱原因碼  
  8 登錄名稱記號不存在。 請確定所傳遞的登錄名稱是有效的。
  10 連線無法使用。在取得連線要求之前,已過了等待時間。 應用程式行為是多樣的。請等待並重試,或是接受這項失敗的「呼叫 API」呼叫。另一個選項是在「登錄 API」呼叫上增加連線數上限設定。
  16 要求服務名稱的長度無效。 請更正程式,然後嘗試重新呼叫。
  18 回應長度超出系統限制。 訊息大小超過 Liberty 伺服器可支援的大小。請驗證大小是有效的。如果大小有效,請確定 Liberty 伺服器的大小足以容納訊息大小。
  19 呼叫本端通訊服務時,收到非零的回覆碼。  
  21 呼叫本端通訊服務時,收到非零的回覆碼。  
24 登錄呼叫成功之後,從儲存區取得連線時發生錯誤。 請驗證伺服器已啟動。如果不在運作中,請重新啟動伺服器,然後重試 API 要求。
  26 廣域交易無法開始。  
  28 找到登錄,但卻不在作用中。  
  32 API 呼叫上的要求類型無效。 要求類型參數無效。請更正程式,然後嘗試重新呼叫。
  34 找不到目標服務。 請確定包含目標 Enterprise Bean 的應用程式已安裝在目標 Liberty 伺服器中,並且已啟動。
  36 連線狀態無效。 用於這項要求的連線控點被判定處於錯誤狀態。請參閱 API 說明文件,取得連線狀態的規則。
  38 用戶端連線控點無效。 用於這項要求的用戶端連線控點被判定無效。請參閱 API 說明文件,取得用戶端連線控點的相關資訊。
  40 發生本端通訊錯誤。 請檢查 Liberty 伺服器日誌,取得任何本端通訊錯誤訊息。
  44 目標 Enterprise Bean 中發生異常狀況或非預期的狀況。 請參閱 Liberty 伺服器日誌,以檢閱異常狀況資料。
  46 本端通訊傳送要求中發生錯誤。 請參閱 Liberty 伺服器日誌,以判斷錯誤。
  48 本端通訊讀取要求中發生錯誤。 請檢查 Liberty 伺服器日誌,以判斷錯誤。
  72 回應長度的輸入參數不夠大,無法包含回應訊息。 只會傳回訊息的一部分。其餘部分會捨棄。請參閱回覆值,取得訊息回應的大小。
  98 無法存取所提供之要求緩衝區的開頭。 請確定所提供的要求緩衝區位址和長度正確。
  100 無法存取所提供之要求緩衝區的結尾。 請確定所提供的要求緩衝區位址和長度正確。
  102 無法存取所提供之回應緩衝區的開頭。 請確定所提供的回應緩衝區位址和長度正確。
  104 無法存取所提供之回應緩衝區的結尾。 請確定所提供的回應緩衝區位址和長度正確。
 

224

找到不完整的登錄。 這是一個非預期的狀況。 請利用 BBOA1URG 服務來取消登錄,然後利用 BBOA1REG 服務來重新登錄。
 

226

找到不完整的連線控點。 這是一個非預期的狀況。 請利用 BBOA1INV 服務來重新嘗試要求。
 

480

用戶端無法成為獲授權呼叫 invoke 功能。 這是一個非預期的狀況。 請確定目標伺服器在執行中,且伺服器實例配置了 zosLocalAdapters 服務。
 

482

在伺服器重新啟動之後,用戶端無法重新連接至目標伺服器實例。 這是一個非預期的狀況。 請利用 BBOA1URG 服務來移除登錄,然後利用 BBOA1REG 服務來建立一個新的登錄。
 

483

在伺服器重新啟動之後,用戶端無法重新連接至目標伺服器實例。 這是一個非預期的狀況。 請利用 BBOA1URG 服務來移除登錄,然後利用 BBOA1REG 服務來建立一個新的登錄。
12 10 API 找不到選取的最佳化本端配接器群組。 請確定 Liberty 伺服器和目標伺服器已啟動,並驗證最佳化本端配接器支援為作用中,然後再試一次。
 

14

該使用者 ID 未獲授權使用所要求的 Liberty 伺服器。 請確定該使用者 ID 獲權使用所要求之 Liberty 伺服器的 CBIND SAF 類別。
  24 登錄呼叫成功之後,從連線儲存區取得連線時發生錯誤。 請驗證伺服器已啟動。如果尚未啟動,請重新啟動伺服器,然後重試 API 要求。
  86 找不到 Liberty 伺服器的主要 BGVT。 Liberty 伺服器未在現行 z/OS 作業系統映像檔上啟動。在您啟動任何最佳化本端配接器用戶端程序之前,請確定伺服器已啟動。
  88 找不到 Liberty 伺服器的主要用戶端 Stub 表格。 Liberty 伺服器已在現行 z/OS 作業系統映像檔上啟動,但是伺服器不是在支援最佳化本端配接器用戶端 Stub 表格的層次執行。請確定與應用程式搭配執行的最佳化本端配接器 Stub 的層次,相容於這個 z/OS 系統上的 Liberty 伺服器。
  90 找不到 Liberty 伺服器最佳化本端配接器的主要用戶端 Stub 表格位置。 Liberty 伺服器已在現行 z/OS 作業系統映像檔上啟動,但是伺服器不是在支援最佳化本端配接器用戶端 Stub 表格的層次執行。請確定與應用程式搭配執行的最佳化本端配接器 Stub 的層次,相容於這個 z/OS 系統上的 Liberty 伺服器。

主機服務

「主機服務 API」會使用其他的基礎 API 基本函數,針對從本端 Liberty 伺服器發出的最佳化本端配接器呼叫,將原生語言 z/OS 程式設定成伺服器和目標。在您呼叫 API 之前,如果您知道要求區域的大小上限,請使用 API。
表 25. BBOA1SRV API 語法
API 語法
BBOA1SRV BBOA1SRV (registername, requestservicename, requestservicenamel, requestdata, requestdatalen, connectionhandle, waittime, rc, rsn, rv)
BBOA1SRV API 接受下列輸入參數:
registername
為項目變數或項目常數,包含用來尋找連線儲存區的名稱,以便從這項呼叫擷取連線。值必須是一個用空格填補且剛好 12 個字元的字串。
requestdata
31 位元指標,指向所接收之要求資料開頭的位址。這個參數指向的儲存體,必須位於呼叫端可以寫入的索引鍵中。
requestdatalen
32 位元不帶正負號的值,包含要接收訊息之資料區域的長度。
connectionhandle
12 位元組連線控點,要傳回給呼叫端,並用於傳送這項要求的回應。
waittime
一個整數,含有在傳回「連線無法使用」原因碼之前,要等待連線完成的秒數。值 0(零)意指沒有逾時,且 API 會無限期地等待。waittime 參數只適用於從連線儲存區取得 WOLA 連線的程序。取得的連線會用來接收伺服器的要求,且等待時間無限制。
BBOA1SRV API 接受下列輸入或輸出參數:
requestservicename
EBCDIC 字串,長度最多 256 個位元組,包含服務的名稱。這個參數是 Liberty 伺服器應用程式在 InteractionSpec 介面中指定的目標服務名稱。值 * 表示設定為在現行登錄名稱之下送達之所有服務名稱的伺服器。
requestservicenamel
一個整數,含有要啟動之服務名稱的長度,如果服務名稱以空值結尾,則為 0
BBOA1SRV API 接受下列輸出參數:
rc
整數的回覆碼,指出這項呼叫成功或失敗。
rsn
整數的原因碼,說明這項呼叫失敗的原因。
rv
32 位元整數回覆值,含有已接收並複製到呼叫端回應區域的訊息資料的大小。
使用注意事項:
  • 請確定您在這項呼叫中指定的 Liberty 伺服器已啟動,並且已啟用本端配接器支援。
  • 在使用「登錄 API」之前,請確定在具有相符名稱的現行位址空間中,該 API 呼叫已順利完成。
  • 如果 API 呼叫端輸入的 requestdatalen 參數大於實際訊息回應,回覆碼會包含 0(零),且會在回覆值中提供實際訊息長度。
  • 如果這項「主機服務」使用「傳送回應 API」,必須在任何回應中提供所傳回的連線控點。
回覆碼和原因碼:
表 26. BBOA1SRV API 回覆碼和原因碼
回覆碼 原因碼 說明 動作
0 - 成功  
4 - 警告 - 請參閱原因碼  
8 - 錯誤 - 請參閱原因碼  
  8 該登錄名稱記號已存在。 請確定所傳遞的登錄名稱是有效的。
  10 連線控點處於已釋放狀態。 請確定所傳遞的連線控點正確。
  12 連線控點不在登錄名稱中的連線上。 請更正程式,然後嘗試重新呼叫。
  16 要求服務名稱的長度無效。 請更正程式,然後嘗試重新呼叫。
  18 回應長度超出系統限制。 訊息大小超過 Liberty 伺服器可支援的大小。請驗證大小是有效的。如果大小有效,請確定 Liberty 伺服器的大小足以容納訊息大小。
  40 發生本端通訊錯誤。 請檢查 Liberty 伺服器日誌,取得任何本端通訊錯誤訊息。
  46 本端通訊傳送要求中發生錯誤。 請檢查 Liberty 伺服器日誌,以判斷錯誤。
  48 本端通訊讀取要求中發生錯誤。 請檢查 Liberty 伺服器日誌,以判斷錯誤。
  72 回應長度的輸入參數不夠大,無法包含回應訊息。 只會傳回訊息的一部分。其餘部分會捨棄。請參閱回覆值,取得訊息回應的大小。
  98 無法存取所提供之要求緩衝區的開頭。 請確定所提供的要求緩衝區位址和長度正確。
  100 無法存取所提供之要求緩衝區的結尾。 請確定所提供的要求緩衝區位址和長度正確。
 

224

找到不完整的登錄。 這是一個非預期的狀況。 請利用 BBOA1URG 服務來取消登錄,然後利用 BBOA1REG 服務來重新登錄。
 

226

找到不完整的連線控點。 這是一個非預期的狀況。 請利用 BBOA1SRV 服務來重新嘗試要求。
 

480

用戶端無法成為獲授權呼叫主機功能。 這是一個非預期的狀況。 請確定目標伺服器在執行中,且伺服器實例配置了 zosLocalAdapters 服務。
 

482

在伺服器重新啟動之後,用戶端無法重新連接至目標伺服器實例。 這是一個非預期的狀況。 請利用 BBOA1URG 服務來移除登錄,然後利用 BBOA1REG 服務來建立一個新的登錄。
 

483

在伺服器重新啟動之後,用戶端無法重新連接至目標伺服器實例。 這是一個非預期的狀況。 請利用 BBOA1URG 服務來移除登錄,然後利用 BBOA1REG 服務來建立一個新的登錄。
12 10 API 找不到選取的最佳化本端配接器群組。 請確定 Liberty 伺服器和目標伺服器已啟動,並驗證最佳化本端配接器支援為作用中,然後再試一次。
 

14

該使用者 ID 未獲授權使用所要求的 Liberty 伺服器。 請確定該使用者 ID 獲權使用所要求之 Liberty 伺服器的 CBIND SAF 類別。
  86 找不到 Liberty 伺服器的主要 BGVT。 Liberty 伺服器未在現行 z/OS 作業系統映像檔上啟動。在您啟動任何最佳化本端配接器用戶端程序之前,請確定伺服器已啟動。
  88 找不到 Liberty 伺服器的主要用戶端 Stub 表格。 Liberty 伺服器已在現行 z/OS 作業系統映像檔上啟動,但是伺服器不是在支援最佳化本端配接器用戶端 Stub 表格的層次執行。請確定與應用程式搭配執行的最佳化本端配接器 Stub 的層次,相容於這個 z/OS 系統上的 Liberty 伺服器。
  90 找不到 Liberty 伺服器最佳化本端配接器的主要用戶端 Stub 表格位置。 Liberty 伺服器已在現行 z/OS 作業系統映像檔上啟動,但是伺服器不是在支援最佳化本端配接器用戶端 Stub 表格的層次執行。請確定與應用程式搭配執行的最佳化本端配接器 Stub 的層次,相容於這個 z/OS 系統上的 Liberty 伺服器。

Java EE 連接器架構 (JCA) 配接器 API

如果是從 Liberty 伺服器呼叫批次程式或子系統,Liberty 伺服器應用程式會使用標準 JCA API。下列介面是自訂成與最佳化本端配接器搭配使用:
  • ConnectionSpec
  • InteractionSpec
  • Record I/O

ConnectionSpec

當您從 Connection Factory 取得連線時,請使用 ConnectionSpec 介面來傳遞連線特定的參數。這些參數可以置換定義在 Connection Factory 中的同名參數。對於最佳化本端配接器,這個介面會實作成 com.ibm.websphere.ola.ConnectionSpecImpl 類別。ConnectionSpecImpl 類別可讓您指定要與哪個最佳化本端配接器登錄名稱進行通訊。

當您與 CICS 鏈結伺服器通訊時,ConnectionSpecImpl 類別會提供方法,讓您用來置換鏈結伺服器使用的值。例如,您可以針對鏈結伺服器呼叫交易 BBO#,指定 4 個字元的交易 ID。您也可以指定要將要求資料儲存在 CICS COMMAREA 或 CONTAINER 物件中。

如需 ConnectionSpecImpl 類別中的方法的相關資訊,請參閱產生的 API 說明文件

InteractionSpec

使用 InteractionSpec 介面,指定要求特定的參數給您要連接的資源配接器實例。對於最佳化本端配接器,這個介面會實作成 com.ibm.websphere.ola.InteractionSpecImpl 類別。您可以使用 InteractionSpecImpl 類別來設定服務名稱,使應用程式與之通訊。服務名稱由您取得連線時所指定的登錄名稱管理。

如需 InteractionSpecImpl 類別中的方法的相關資訊,請參閱產生的 API 說明文件

Record I/O

使用 Record 介面,將要求和回應資料傳遞給您要連接的資源配接器實例。最佳化本端配接器提供兩種 Record 介面實作:IndexedRecord 和 MappedRecord。您可以從應用程式使用的 JCA 連線實例,取得 RecordFactory 的參照,來建立這兩種實作。

如果您要將資料傳遞至「批次」或「UNIX 系統服務」程式,或者您要使用 COMMAREA 或單一 CONTAINER 物件,來與 CICS 通訊,請使用 IndexedRecord 物件。請在 IndexRecord 物件中新增位元組陣列 (byte[]),來代表程式要在要求中傳送的資料。所收到的回應也會放到 IndexedRecord 物件中。您可以從 IndexedRecord 物件擷取第一個項目,並強制轉型為位元組陣列,來取得回應資料。

如果您要將資料傳遞至多個 CONTAINER 物件中的 CICS,請使用 MappedRecord 物件。MappedRecord 物件包含名稱/值配對,這與 Map 物件所儲存的類似。在名稱/值配對中,名稱是指傳送資料時的目標儲存器名稱,值是指指定成位元組陣列 (byte[]) 的實際資料。當您使用 MappedRecord 物件傳送要求時,也會使用 MappedRecord 物件送回回應。回應含有包含回應資料和相關聯資料之每一個儲存器的名稱。


指示主題類型的圖示 參照主題

檔名:rwlp_dat_olaapis.html