有一組 z/OS® 原生語言可呼叫服務應用程式設計介面 (API) 和 Java™ EE 連接器架構 (JCA),支援 Liberty 上的 WebSphere® 最佳化本端配接器 (WOLA)。
您可以從下列原生程式設計語言,來使用可呼叫的服務:
本端連線一詞是指針對 z/OS 系統上的外部位址空間與相同 z/OS 系統上的 Liberty 伺服器之間的通訊,所建立的跨記憶體鏈結。用戶端位址空間必須在相同 z/OS 映像檔上執行。配接器 API 在與每一個唯一登錄的呼叫端相關聯的儲存區中,管理這些本端連線。在每一個位址空間中,登錄名稱(12 個字元)只能用於其中的一組連線儲存區。單一位址空間中的唯一登錄數目,只受可用的儲存體量限制。
Liberty 支援下列的最佳化本端配接器 API:
登錄
使用 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 個字元的字串,並且不能在現行位址空間中使用。
- 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
- 整數的原因碼,說明這項呼叫失敗的原因。
回覆碼和原因碼:
表 2. BBOA1REG API 回覆碼和原因碼| 回覆碼 |
原因碼 |
說明 |
動作 |
| 0 |
- |
成功 |
|
| 8 |
- |
錯誤 - 請參閱原因碼 |
|
| |
8 |
該登錄名稱記號已存在。 |
在呼叫「登錄」API 之前,請先取消登錄這個名稱。 |
| |
12 |
指定的連線數下限參數大於上限。 |
請確定連線數下限設定小於或等於上限設定。 |
| |
14 |
嘗試建立登錄時,共用記憶體不足。 |
請增加最佳化本端配接器的共用記憶體配置,或是發出取消登錄呼叫,來減少資源耗用。 |
| |
25 |
無法起始交易管理程式。 |
請參閱 WebSphere Application Server 支援網站上的問題判斷資訊。 |
| |
70 |
嘗試建立連線時,共用記憶體不足。 |
請增加最佳化本端配接器的共用記憶體配置。 |
| |
74 |
輸入登錄名稱包含空值。 |
呼叫「登錄」API 之前,請先用空格填補登錄名稱,使名稱長度剛好是 12 個字元。 |
| 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 伺服器。 |
取消登錄
使用 BBOA1URG API,從本端的最佳化本端配接器群組和 Liberty 伺服器取消登錄。
表 3. BBOA1URG API 語法. 這個 API 要求使用指定的登錄名稱,釋放指向本端的最佳化本端配接器群組和 Liberty 伺服器的最佳化連線群組。| API |
語法 |
| BBOA1URG |
BBOA1URG (registername, unregflags,
rc, rsn) |
BBOA1URG API 接受下列輸入參數:
- registername
- 為項目變數或項目常數,包含用來取消登錄一組本端連線的名稱。值必須剛好 12 個字元,用空格填補,並且是「登錄」API 呼叫上所使用的相同名稱。
- unregisterflags
-
BBOA1URG API接受下列輸出參數:
- rc
- 整數的回覆碼,指出這項呼叫成功或失敗。
- rsn
- 整數的原因碼,說明這項呼叫失敗的原因。
使用注意事項:
- 請確定您在這項呼叫中指定的 Liberty 伺服器已啟動,並且已啟用本端配接器支援。
- 如果沒有呼叫「取消登錄」API,且發出登錄呼叫的位址空間終止,會自動完成取消登錄呼叫,並釋放連線。
- 進行取消登錄呼叫期間,這項登錄的任何處於作用中的連線控點可能繼續維持有效,直到使用「釋放連線」API 將它們傳回到連線儲存區為止。如果要強制清除連線控點,必須發出第二項取消登錄呼叫,並指定 force 旗標。這會讓所有未完成的連線控點失效。
回覆碼和原因碼:
表 4. BBOA1URG API 回覆碼和原因碼| 回覆碼 |
原因碼 |
說明 |
動作 |
| 0 |
- |
成功 |
|
| 4 |
- |
警告 - 請參閱原因碼 |
|
| |
66 |
取消登錄呼叫一直延遲到所有連線皆傳回到儲存區為止。 |
當最後一條連線傳回到可用儲存區時,取消登錄即告完成。 |
| 8 |
- |
錯誤 - 請參閱原因碼 |
|
| |
8 |
該登錄記號名稱不存在。 |
您必須先登錄這個名稱,再為它呼叫「取消登錄」API。 |
| |
64 |
必須等發出正常的取消登錄之後,才能指定 force 選項。 |
請在呼叫「取消登錄」API 時,不要指定 force 選項。 |
| |
76 |
嘗試與伺服器通訊失敗,因為伺服器不再執行。 |
請啟動伺服器,並嘗試重新通訊。 |
| |
82 |
已嘗試取消登錄這項登錄。 |
請等待先前的取消登錄要求完成,或重新發出這項取消登錄,並使用 force 選項。 |
| 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 會無限期地等待。
BBOA1CNG API 接受下列輸出參數:
- rc
- 整數的回覆碼,指出這項呼叫成功或失敗。
- rsn
- 整數的原因碼,說明這項呼叫失敗的原因。
使用注意事項:
- 請確定您在這項呼叫中指定的 Liberty 伺服器已啟動,並且已啟用本端配接器支援。
- 在使用「取得連線」API 之前,請確定在具有相符名稱的現行位址空間中,「登錄」API 呼叫已順利完成。
回覆碼和原因碼:
表 6. BBOA1CNG API 回覆碼和原因碼| 回覆碼 |
原因碼 |
說明 |
動作 |
| 0 |
- |
成功 |
|
| 4 |
- |
警告 - 請參閱原因碼 |
|
| 8 |
- |
錯誤 - 請參閱原因碼 |
|
| |
8 |
該登錄名稱記號不存在。 |
請先登錄這個名稱,再用「取得連線」API 呼叫這個名稱。 |
| |
10 |
連線無法使用。在可以取得連線要求之前,已過了等待時間。 |
應用程式行為是多樣的。請等待然後再試一次,或是發出異常終止巨集,來終止呼叫「取得連線」API 的作業。您也可以在「登錄」API 呼叫上增加連線數上限設定。 |
| |
24 |
登錄呼叫成功之後,從儲存區取得連線時發生錯誤。 |
請驗證伺服器已啟動。如果不在運作中,請重新啟動伺服器,然後重試 API 要求。 |
| |
28 |
找到登錄,但卻不在作用中。 |
|
| 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 要求將連線傳回到從中擷取的儲存區,讓另一個要求端可以使用它。
表 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 |
14 |
找不到或無法驗證使用所提供的連線控點的 API 呼叫向量。 |
連線控點無效,或者「取消登錄」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 伺服器來進行處理。
表 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 |
該登錄名稱記號已存在。 |
請確定所傳遞的登錄名稱是有效的。 |
| |
14 |
儲存訊息時,發生記憶體不足狀況。 |
沒有足夠的可用記憶體供「傳送要求」處理訊息。現行位址空間的專用儲存體不足。 |
| |
16 |
要求服務名稱的長度無效。 |
請更正程式,然後再試一次。 |
| |
18 |
要求長度超出系統限制。 |
訊息大小超過 Liberty 伺服器可支援的大小。請驗證大小是有效的。如果大小有效,請確定 Liberty 伺服器的大小足以容納訊息大小。 |
| |
26 |
廣域交易無法開始。 |
|
| |
32 |
API 呼叫要求類型無效。 |
要求類型無效。請更正程式,然後嘗試重新呼叫。 |
| |
34 |
找不到目標服務。 |
請確定包含目標 Enterprise Bean 的應用程式已安裝在 Liberty 伺服器的目標伺服器中,並且已啟動。 |
| |
36 |
連線狀態無效。 |
用於要求的連線控點處於錯誤狀態。請參閱 API 文件,取得連線狀態的規則。 |
| |
38 |
用戶端連線控點無效。 |
用於要求的用戶端連線控點無效。請參閱 API 文件,取得用戶端連線控點的相關資訊。 |
| |
40 |
發生本端通訊錯誤。 |
請檢查 Liberty 伺服器日誌,取得任何本端通訊錯誤訊息。 |
| |
44 |
目標 Enterprise Bean 中發生異常狀況或非預期的狀況。 |
請參閱 Liberty 伺服器日誌,以檢閱異常狀況資料。 |
| |
46 |
本端通訊傳送要求呼叫中發生錯誤。 |
請檢查 Liberty 伺服器日誌,以判斷錯誤。 |
| |
98 |
無法存取所提供之要求緩衝區的開頭。 |
請確定所提供的要求緩衝區位址和長度正確。 |
| |
100 |
無法存取所提供之要求緩衝區的結尾。 |
請確定所提供的要求緩衝區位址和長度正確。 |
| 12 |
10 |
API 找不到選取的最佳化本端配接器群組。 |
請確定 Liberty 伺服器和目標伺服器已啟動,並驗證最佳化本端配接器支援為作用中,然後再試一次。 |
| |
14 |
找不到或無法驗證使用所提供的連線控點的 API 呼叫向量。 |
連線控點無效,或者取消登錄呼叫 (BBOA1URG 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 伺服器。
表 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 被視為有效的狀態。
回覆碼和原因碼:
表 12. BBOA1SRP API 回覆碼和原因碼| 回覆碼 |
原因碼 |
說明 |
動作 |
| 0 |
- |
成功 |
|
| 4 |
- |
警告 - 請參閱原因碼 |
|
| 8 |
- |
錯誤 - 請參閱原因碼 |
|
| |
8 |
該登錄名稱記號已存在。 |
請確定所傳遞的登錄名稱是有效的。 |
| |
14 |
儲存訊息時,發生記憶體不足狀況。 |
沒有足夠的可用記憶體供「傳送回應」API 處理訊息。現行位址空間的專用儲存體不足。 |
| |
18 |
要求長度超出系統限制。 |
訊息大小超過 Liberty 伺服器可支援的大小。請驗證大小是有效的。如果大小有效,請確定 Liberty 伺服器的大小足以容納訊息大小。 |
| |
34 |
找不到目標服務。 |
請確定包含目標 Enterprise Bean 的應用程式已安裝在 Liberty 伺服器的目標伺服器中,並且已啟動。 |
| |
36 |
連線狀態無效。 |
用於要求的連線控點處於錯誤狀態。請參閱 API 文件,取得連線狀態的規則。 |
| |
38 |
用戶端連線控點無效。 |
用於要求的用戶端連線控點無效。請參閱 API 文件,取得用戶端連線控點的相關資訊。 |
| |
40 |
發生本端通訊錯誤。 |
請檢查 Liberty 伺服器日誌,取得任何本端通訊錯誤訊息。 |
| |
46 |
本端通訊傳送要求呼叫中發生錯誤。 |
請檢查 Liberty 伺服器日誌,以判斷錯誤。 |
| |
102 |
無法存取所提供之回應緩衝區的開頭。 |
請確定所提供的回應緩衝區位址和長度正確。 |
| |
104 |
無法存取所提供之回應緩衝區的結尾。 |
請確定所提供的回應緩衝區位址和長度正確。 |
| 12 |
10 |
API 找不到選取的最佳化本端配接器群組。 |
請確定 Liberty 伺服器和目標伺服器已啟動,並驗證最佳化本端配接器支援為作用中,然後再試一次。 |
| |
14 |
找不到或無法驗證使用所提供的連線控點的 API 呼叫向量。 |
連線控點無效,或者取消登錄呼叫 (BBOA1URG 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 會傳送 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 被視為有效的狀態。
回覆碼和原因碼:
表 14. BBOA1SRX API 回覆碼和原因碼| 回覆碼 |
原因碼 |
說明 |
動作 |
| 0 |
- |
成功 |
|
| 4 |
- |
警告 - 請參閱原因碼 |
|
| 8 |
- |
錯誤 - 請參閱原因碼 |
|
| |
8 |
該登錄名稱記號已存在。 |
請確定所傳遞的登錄名稱是有效的。 |
| |
10 |
連線控點處於已釋放或無效的狀態。 |
請確定所傳遞的連線控點是有效的。 |
| |
14 |
儲存訊息時,發生記憶體不足狀況。 |
沒有足夠的可用記憶體供「傳送回應異常狀況」API 處理訊息。現行位址空間的專用儲存體不足。 |
| |
16 |
一或多個參數無效。 |
請驗證所有參數都是有效的,然後嘗試重新呼叫。 |
| |
18 |
要求長度超出系統限制。 |
訊息大小超過 Liberty 伺服器可支援的大小。請驗證大小是有效的。如果大小有效,請確定 Liberty 伺服器的大小足以容納訊息大小。 |
| |
20 |
一或多個參數無效。 |
請驗證所有參數都是有效的,然後嘗試重新呼叫。 |
| |
28 |
連線控點相關聯的登錄不再是作用中。 |
請重新利用登錄名稱來呼叫「登錄」API,然後呼叫「取得連線」和「傳送要求」API。 |
| |
36 |
連線狀態無效。 |
用於這項要求的連線控點處於錯誤狀態。請參閱 API 文件,取得連線狀態的規則。 |
| |
38 |
用戶端連線控點無效。 |
用於這項要求的用戶端連線控點無效。請參閱 API 文件,取得用戶端連線控點的相關資訊。 |
| |
40 |
發生本端通訊錯誤。 |
請檢查 Liberty 伺服器日誌,取得任何本端通訊錯誤訊息。 |
| |
46 |
本端通訊傳送要求呼叫中發生錯誤。 |
請檢查 Liberty 伺服器日誌,以判斷錯誤。 |
| |
102 |
無法存取所提供之回應緩衝區的開頭。 |
請確定所提供的回應緩衝區位址和長度正確。 |
| |
104 |
無法存取所提供之回應緩衝區的結尾。 |
請確定所提供的回應緩衝區位址和長度正確。 |
| 12 |
10 |
API 找不到選取的最佳化本端配接器群組。 |
請確定 Liberty 伺服器和目標伺服器已啟動,並驗證最佳化本端配接器支援為作用中,然後再試一次。 |
| |
14 |
找不到或無法驗證使用所提供的連線控點的 API 呼叫向量。 |
連線控點無效,或者取消登錄呼叫 (BBOA1URG 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 時,會傳回所接收的訊息資料。
表 15. BBOA1RCA API 語法| API |
語法 |
| BBOA1RCA |
BBOA1RCA (registername, connectionhandle,
requestservicename, requestservicenamel, requestdatalen, waittime,
rc, rsn) |
BBOA1RCA API 接受下列輸入參數:
- registername
- 為項目變數或項目常數,包含用來尋找連線儲存區的名稱,以便從該連線儲存區擷取連線。值必須是一個用空格填補且剛好 12 個字元的字串。
- waittime
- 一個整數,含有在傳回「連線無法使用」原因碼之前,要等待連線完成的秒數。值 0 表示沒有等待時間,API 會無限期地等待。
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 |
該登錄名稱記號已存在。 |
請確定所傳遞的登錄名稱是有效的。 |
| |
11 |
從 Liberty 伺服器傳送的資料不當。 |
|
| |
16 |
要求服務名稱的長度無效。 |
請更正程式,然後嘗試重新呼叫。 |
| |
19 |
呼叫本端通訊服務時,收到非零的回覆碼。 |
|
| |
21 |
呼叫本端通訊服務時,收到非零的回覆碼。 |
|
| |
38 |
用戶端連線控點無效。 |
用於這項要求的用戶端連線控點被判定無效。請參閱 API 文件,取得用戶端連線控點的相關資訊。 |
| |
40 |
發生本端通訊錯誤。 |
請檢查 Liberty 伺服器日誌,取得任何本端通訊錯誤訊息。 |
| |
46 |
本端通訊傳送要求呼叫中發生錯誤。 |
請檢查 Liberty 伺服器日誌,以判斷錯誤。 |
| |
76 |
嘗試與伺服器通訊失敗,因為伺服器不再執行。 |
請啟動伺服器,並嘗試重新通訊。 |
| 12 |
10 |
API 找不到選取的最佳化本端配接器群組。 |
請確定 Liberty 伺服器和目標伺服器已啟動,並驗證最佳化本端配接器支援為作用中,然後再試一次。 |
| |
24 |
登錄呼叫成功之後,從儲存區取得連線時發生錯誤。 |
請驗證伺服器已啟動。如果伺服器未啟動,請重新啟動伺服器,然後重試 API 要求。 |
| |
44 |
呼叫 CSRC4BLD z/OS 服務失敗。 |
|
| |
46 |
呼叫 CSRC4GT1 z/OS 服務失敗。 |
|
| |
48 |
呼叫 CSRC4FR1 z/OS 服務失敗。 |
|
| |
60 |
API 服務無法取得服務佇列鎖定。 |
|
| |
62 |
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 |
連線控點處於已釋放或不適當的狀態。 |
請確定所傳遞的連線控點是有效的。 |
| |
11 |
從 Liberty 伺服器傳送的資料不當 |
|
| |
16 |
要求服務名稱的長度無效。 |
請更正程式,然後嘗試重新呼叫。 |
| |
19 |
呼叫本端通訊服務時,收到非零的回覆碼。 |
|
| |
21 |
呼叫本端通訊服務時,收到非零的回覆碼。 |
|
| |
28 |
連線控點相關聯的登錄不再是作用中。 |
請重新呼叫登錄名稱,然後呼叫「取得連線」和「接收要求(特定)」。 |
| |
36 |
連線狀態無效。 |
用於這項要求的連線控點處於錯誤狀態。請參閱 API 文件,取得連線狀態的規則。 |
| |
38 |
用戶端連線控點無效。 |
用於這項要求的用戶端連線控點無效。請參閱 API 文件,取得用戶端連線控點的相關資訊。 |
| |
40 |
發生本端通訊錯誤。 |
請檢查 Liberty 伺服器日誌,取得任何本端通訊錯誤訊息。 |
| |
46 |
本端通訊傳送要求呼叫中發生錯誤。 |
請檢查 Liberty 伺服器日誌,以判斷錯誤。 |
| |
76 |
嘗試與伺服器通訊失敗,因為伺服器不再執行。 |
請啟動伺服器,並嘗試重新通訊。 |
| |
78 |
發生內部錯誤,導致連線選取的要求不是這條連線要處理之交易的一部分。 |
請將連線傳回到連線儲存區。如果問題仍在,請參閱 WebSphere Application Server 支援中心網站上的問題判斷資訊。 |
| |
80 |
這條連線上的作用中交易發生逾時,且無法重設連線狀態,因此改處理另一項要求。 |
請將連線傳回到連線儲存區。如果問題仍在,請參閱 WebSphere Application Server 支援中心網站上的問題判斷資訊。 |
| 12 |
10 |
API 找不到選取的最佳化本端配接器群組。 |
請確定 Liberty 伺服器和目標伺服器已啟動,並驗證最佳化本端配接器支援為作用中,然後再試一次。 |
| |
14 |
找不到或無法驗證使用所提供的連線控點的 API 呼叫向量。 |
連線控點無效,或者取消登錄呼叫 (BBOA1URG API) 可能已讓連線儲存區失效。 |
| |
44 |
呼叫 CSRC4BLD z/OS 服務失敗。 |
|
| |
46 |
呼叫 CSRC4GT1 z/OS 服務失敗。 |
|
| |
48 |
呼叫 CSRC4FR1 z/OS 服務失敗。 |
|
| |
60 |
API 服務無法取得服務佇列鎖定。 |
|
| |
62 |
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 會從先前的「傳送要求」呼叫,擷取回應資料的長度。
表 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 |
該登錄名稱記號已存在。 |
請確定所傳遞的登錄名稱是有效的。 |
| |
11 |
從 Liberty 伺服器傳送的資料不當。 |
|
| |
19 |
呼叫本端通訊服務時,收到非零的回覆碼。 |
|
| |
21 |
呼叫本端通訊服務時,收到非零的回覆碼。 |
|
| |
36 |
連線狀態無效。 |
用於這項要求的連線控點被判定處於錯誤狀態。請參閱 API 文件,取得連線狀態的規則。 |
| |
38 |
用戶端連線控點無效。 |
用於這項要求的用戶端連線控點被判定無效。請參閱 API 文件,取得用戶端連線控點的相關資訊。 |
| |
40 |
發生本端通訊錯誤。 |
請檢查 Liberty 伺服器日誌,取得任何本端通訊錯誤訊息。 |
| 12 |
10 |
API 找不到選取的最佳化本端配接器群組。 |
請確定 Liberty 伺服器和目標伺服器已啟動,並驗證最佳化本端配接器支援為作用中,然後再試一次。 |
| |
14 |
找不到或無法驗證使用所提供的連線控點的 API 呼叫向量。 |
連線控點無效,或者「取消登錄」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 呼叫傳回時,會將訊息從配接器訊息快取中移除。
表 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 位元整數回覆值,含有這項要求的環境定義緩衝區大小。
回覆碼和原因碼:
表 22. BBOA1GET API 回覆碼和原因碼| 回覆碼 |
原因碼 |
說明 |
動作 |
| 0 |
- |
成功 |
|
| 4 |
- |
警告 - 請參閱原因碼 |
|
| 8 |
- |
錯誤 - 請參閱原因碼 |
|
| |
8 |
該登錄名稱記號已存在。 |
請確定所傳遞的登錄名稱是有效的。 |
| |
36 |
連線狀態無效。 |
用於這項要求的連線控點被判定處於錯誤狀態。請參閱 API 文件,取得連線狀態的規則。 |
| |
38 |
用戶端連線控點無效。 |
用於這項要求的用戶端連線控點被判定無效。請參閱 API 文件,取得用戶端連線控點的相關資訊。 |
| |
40 |
發生本端通訊錯誤。 |
請檢查 Liberty 伺服器日誌,取得任何本端通訊錯誤訊息。 |
| |
48 |
本端通訊讀取要求中發生錯誤。 |
請檢查 Liberty 伺服器日誌,以判斷錯誤。 |
| |
50 |
與 Liberty 伺服器的連線已終止。 |
請檢查 Liberty 伺服器日誌,以判斷錯誤。 |
| |
72 |
回應長度的輸入參數不夠大,無法包含回應訊息。 |
只會傳回訊息的一部分。其餘部分會捨棄。請參閱回覆值,取得訊息回應的大小。 |
| |
98 |
無法存取所提供之要求緩衝區的開頭。 |
請確定所提供的要求緩衝區位址和長度正確。 |
| |
100 |
無法存取所提供之要求緩衝區的結尾。 |
請確定所提供的要求緩衝區位址和長度正確。 |
| |
102 |
無法存取所提供之回應緩衝區的開頭。 |
請確定所提供的回應緩衝區位址和長度正確。 |
| |
104 |
無法存取所提供之回應緩衝區的結尾。 |
請確定所提供的回應緩衝區位址和長度正確。 |
| 12 |
10 |
API 找不到選取的最佳化本端配接器群組。 |
請確定 Liberty 伺服器和目標伺服器已啟動,並驗證最佳化本端配接器支援為作用中,然後再試一次。 |
| |
14 |
找不到或無法驗證使用所提供的連線控點的 API 呼叫向量。 |
連線控點無效,或者「取消登錄」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 伺服器中的方法。依照其設計,是在已預先知道回應輸出區域大小上限的情況下使用。
表 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 會無限期地等待。
BBOA1INV API 接受下列輸出參數:
- rc
- 整數的回覆碼,指出這項呼叫成功或失敗。
- rsn
- 整數的原因碼,說明這項呼叫失敗的原因。
- rv
- 32 位元整數回覆值,含有已接收並複製到呼叫端回應區域的訊息資料的大小。
使用注意事項:
- 請確定您在這項呼叫中指定的 Liberty 伺服器已啟動,並且已啟用本端配接器支援。
- 在使用「傳送要求」API 之前,請確定在具有相符名稱的現行位址空間中,「登錄」API 呼叫已順利完成。
- 如果 API 呼叫端輸入的 responsedatalen 參數大於實際訊息回應,回覆碼會包含 0(零),且會在回覆值中提供實際訊息長度。
回覆碼和原因碼:
表 24. BBOA1INV API 回覆碼和原因碼| 回覆碼 |
原因碼 |
說明 |
動作 |
| 0 |
- |
成功 |
|
| 4 |
- |
警告 - 請參閱原因碼 |
|
| 8 |
- |
錯誤 - 請參閱原因碼 |
|
| |
8 |
登錄名稱記號不存在。 |
請確定所傳遞的登錄名稱是有效的。 |
| |
10 |
連線無法使用。在取得連線要求之前,已過了等待時間。 |
應用程式行為是多樣的。請等待並重試,或是接受這項失敗的「呼叫 API」呼叫。另一個選項是在「登錄」API 呼叫上增加連線數上限設定。 |
| |
11 |
從 Liberty 伺服器傳送的資料不當。 |
|
| |
14 |
儲存訊息時,發生記憶體不足狀況。 |
沒有足夠的可用記憶體供「呼叫」處理訊息。現行位址空間的專用儲存體不足。 |
| |
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 伺服器日誌,以判斷錯誤。 |
| |
50 |
與 Liberty 伺服器的連線已終止。 |
請檢查 Liberty 伺服器,以判斷錯誤。 |
| |
72 |
回應長度的輸入參數不夠大,無法包含回應訊息。 |
只會傳回訊息的一部分。其餘部分會捨棄。請參閱回覆值,取得訊息回應的大小。 |
| |
98 |
無法存取所提供之要求緩衝區的開頭。 |
請確定所提供的要求緩衝區位址和長度正確。 |
| |
100 |
無法存取所提供之要求緩衝區的結尾。 |
請確定所提供的要求緩衝區位址和長度正確。 |
| |
102 |
無法存取所提供之回應緩衝區的開頭。 |
請確定所提供的回應緩衝區位址和長度正確。 |
| |
104 |
無法存取所提供之回應緩衝區的結尾。 |
請確定所提供的回應緩衝區位址和長度正確。 |
| 12 |
10 |
API 找不到選取的最佳化本端配接器群組。 |
請確定 Liberty 伺服器和目標伺服器已啟動,並驗證最佳化本端配接器支援為作用中,然後再試一次。 |
| |
14 |
找不到或無法驗證使用所提供的連線控點的 API 呼叫向量。 |
連線控點無效,或者「取消登錄」API 呼叫可能已讓連線儲存區失效。 |
| |
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 會無限期地等待。
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 伺服器日誌,以判斷錯誤。 |
| |
50 |
與 Liberty 伺服器的連線已終止。 |
請檢查 Liberty 伺服器,以判斷錯誤。 |
| |
72 |
回應長度的輸入參數不夠大,無法包含回應訊息。 |
只會傳回訊息的一部分。其餘部分會捨棄。請參閱回覆值,取得訊息回應的大小。 |
| |
76 |
嘗試與伺服器通訊失敗,因為伺服器不再執行。 |
請啟動伺服器,並嘗試重新通訊。 |
| |
98 |
無法存取所提供之要求緩衝區的開頭。 |
請確定所提供的要求緩衝區位址和長度正確。 |
| |
100 |
無法存取所提供之要求緩衝區的結尾。 |
請確定所提供的要求緩衝區位址和長度正確。 |
| 12 |
10 |
API 找不到選取的最佳化本端配接器群組。 |
請確定 Liberty 伺服器和目標伺服器已啟動,並驗證最佳化本端配接器支援為作用中,然後再試一次。 |
| |
14 |
找不到或無法驗證使用所提供的連線控點的 API 呼叫向量。 |
連線控點無效,或者「取消登錄」API 呼叫可能已讓連線儲存區失效。 |
| |
44 |
呼叫 CSRC4BLD z/OS 服務失敗。 |
|
| |
46 |
呼叫 CSRC4GT1 z/OS 服務失敗。 |
|
| |
48 |
呼叫 CSRC4FR1 z/OS 服務失敗。 |
|
| |
60 |
API 服務無法取得服務佇列鎖定。 |
|
| |
62 |
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 伺服器。 |
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 物件送回回應。回應含有包含回應資料和相關聯資料之每一個儲存器的名稱。