使用RMNet 呼叫Web 服務

使用 RMNet 呼叫 Web 服務

本篇內容主要在引導 ACUCOBOL-GT 的程式開發者如何使用 COBOL 程式來與 Web 服務交談。

COBOL 客戶端程式中要呼叫 Web 服務，其大概流程會是

＊進行環境初始化的動作；取得進行要求時所需要的參數內容(從畫面接收或從外部帶入)，

也有機會不需要加入參數來呼叫 Web 服務

＊建立請求呼叫時所需要的 XML 內容

＊處理 HTTP 呼叫時所需的動作，包含初始化

＊處理回應的 XML 內容，並在 COBOL 程式中引用結果

ACUCOBOL-GT 可以利用內建提供的程式庫 RMNet 中的各項函數來進行對 Web 服務的呼叫使

用。要使用 RMNet 程式庫内的函式，需要在環境中導入對 rmnet.dll(或 librmnet64.so)的呼

叫，可以在執行命令列中加入“-y”參數來導入，也可以透過 runtime 設定變數 -

SHARED_LIBRARY_LIST – 來引用。

在使用 RMNnet 內的函式時，首先需要先呼叫 NetInit 來進行初始化。而完成對 RMNet 程式

庫的使用時，要呼叫 NetCleanup 來釋放出在 RMNet 中所配置的所有內部資源。除了這兩個

必定要使用的函式外，要將對資訊的請求傳輸到另一台電腦並等待回應，請使用 HttpGet 函

式。要將訊息發送到另一台電腦並等待回應的訊息，則請使用 HttpPost 函式。請注意，

SOAP 定義了 HTTP 協定，對所有的請求均使用 HttpPost 來進行。

假如在處理要求的過程中有錯誤發生，可以使用 NetGetError 來擷取錯誤的文字描述。除了以

上帶出的幾個函式外，RMNet 還有提供其它函式，關於所有函式的所需參數與參數型態與功

能說明，請參考手冊 ACUCOBOL-GT Documentation Appendices: Appendix I. Library

Routines/RMNet Routines 的內容。

而程式中會牽涉到對 XML 內容的處理，在本篇中將會使用 ACUCOBOL-GT 中處理 XML 的眾多

方式其中一種 -- XML Extensions。為了使用 XML Extensions，本篇中也會輕描淡寫的介紹如何

建立簡易的 XSLT 供 XML Extensions 進行 COBOL 資料與 XML 內容之間的轉換。如果讀者已經

自己有處理 XMLs 的程式邏輯，可以不必在意這一段的內容。

關於 RMNet 與 XML Extensions 的功能是在 ACUCOBOL-GT v9.0 之後才提供，所以在準備進行

測試時，請先確認現在正在使用的 ACUCOBOL-GT 版本是 v9.0(含)之後的版本。

取得 Web 服務的規範

Web 服務通常會透過 WSDL (Web Service Description Language)文件描述 Web 服務的公共接

口。WSDL 以 XML 為基礎對如何與 Web 服務通訊和可供使用的服務進行描述，包含服務如何

被進行呼叫，需要哪些參數，以及該服務所傳回的資料結構。由於 WSDL 是一個非常複雜的

文件且不容易理解，較快速的方式是透過一些現成的工具從 Web 服務的位置取得；也可直接

將 WSDL 匯給工具以正確的產生格式化的 SOAP 要求。只要有要求被產生出來，就可以使用它

來建立 XSLT 樣式表，那些 XSLT 檔案將會被 XML extension 功能所使用。這種被用來取得 Web

服務詮釋資料的工具不少，本篇中將使用 SoapUI，該軟體的官方網站為

www.soapui.org，有 open source 與專業版的不同版本區別，可下載並安裝使用。完成軟

體安裝之後，啟動程式並建立一個對應的專案：

1. 啟動 SoapUI，如果有啟動時出現的介紹畫面或是版本昇級推薦畫面可將其關閉以呈現出整

個工作區域。左側的窗格提供一個區域，用於定義和瀏覽專案及其資產。右側的窗格則用

來包含專案中被選擇的項目內容。

2. 為了要建立新的專案，從選單中選取 File > New SOAP Project。

3. 在 New SOAP Project 的對話視窗中，輸入挑選的專案名稱。(也可先略過，在輸入 WSDL 後

由系統自行代入。)

http://www.soapui.org/

4. 在 Initial WSDL 欄位中輸入 https://www.w3schools.com/xml/tempconvert.asmx?WSDL。(該

服務 url 由 w3school 提供，在本篇中只是拿來當作範例，之後的內容會以該服務為依據，

若有自己的服務也可參考過程進行測試，惟內容得自行對應，請勿以本篇內容當作應得執

行結果。)

5. 確認已選擇 Create Requests:的 check box，這會讓 SoapUI 針對每個 method 建立規範請求

文件。

6. 按下 OK 鍵。

在左側的窗格會出現兩個綁定(binding)，分別是 TempConvertSoap 以及 TempConvertSoap12；

而每個綁定有兩個 methods，分別是 CelsiusToFahrenheit 和 FahrenheitToCelsius。在本篇中將

引用 TempConvertSoap 這個綁定。

https://www.w3schools.com/xml/tempconvert.asmx?WSDL

產生請求與回應的 prototypes

在左側 Navigator 窗格中的 TempConvertSoap 綁定底下，選擇 FahrenheitToCelsius 並展開，在

這個 method 的節點下會存在一個名為 Request 1 的 prototype 請求。

在 Request 1 上用滑鼠連續點兩下，prototype 請求的 XML 內容會在編輯視窗中開啟：

在 prototype 請求內容會以問號字元顯示，代表該處需要一個輸入值來產生有效的請求。在這

個服務範例中，則需要填入一個數字型數值，Web 服務會使用該數值來進行計算轉換成對應

的攝氏溫度回傳。

在<x:Fahrenheit>?</x:Fahrenheit>該行，將‘?’以一個數值取代，譬如 212，該值代表華氏溫

度。

要測試該請求時，按下請求視窗左上方的綠色箭頭圖示( )。

SoapUI 會送出請求給 web 服務並且在右方視窗區內顯示結果。

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"

xmlns:x="https://www.w3schools.com/xml/">

<soapenv:Header/>

<soapenv:Body>

<x:FahrenheitToCelsius>



<x:Fahrenheit>?</x:Fahrenheit>

</x:FahrenheitToCelsius>

</soapenv:Body>

</soapenv:Envelope>

請注意：被產生的 XML 若是像上圖表示般，則需要將 'x/'替換成 'x'—移除 x 字元後的正

斜線。若沒有進行修改，之後送出 request 會因為格式內容錯誤得到失敗的訊息。

綁定(binding)指的是一組可以被叫用的動作或是功能。在不同的 SOAP 版本中，綁定的技

術細節也會不同。

測試的結果會帶回 100 的數字，代表相等於華氏 212 度的攝氏溫度。

到這一階段就代表已經取得請求以及回應兩個必須的 prototype，之後就可藉此來協助建立

COBOL 程式內以 XML Extensions 處理 XML 內容時所需的 XSLT 樣式表。

參考規範建立 COBOL 變數宣告

在成功送出請求給 Web 服務並得到回應後表示整個提出要求/接到回應的動作正常無誤，接

下來就可依內容規劃 COBOL 程式中對此 Web 服務所需用到的 COBOL 變數，做為參考的對象

是 prototype 中的<xxx:Body>這一階層裡面的內容。

請求部份：

預計是要由 COBOL 送出內容給 Web 服務，因此透過 WSDL 取得的規範代表 Web 服務端的定

義，可以仿照其格式來進行預計要提交給 Web 服務的 COBOL 變數的定義：

<soapenv:Body>




<x:Fahrenheit>?</x:Fahrenheit>


</soapenv:Body>

Web 服務端的變數名稱有兩個，分別是

FahrenheitToCelsius以及其階層內的

Fahrenheit。

所以仿照架構將 COBOL 端的變數定義宣告為：

01 Fahrenheit-To-Celsius.

03 Fahrenheit pic ...

至於變數要宣告為何種型態這件事，由於從先前 SoapUI 介面看到的內容裏面並未呈現出來，

並且 ACUCOBOL-GT 相關的軟體中並未像其它語言工具一樣含有從 WSDL 產生語言的 copy

books 的功能，因此需要自行判斷，判斷的依據是 WSDL 本身，可以檢視其內容取得；或者是

利用 SoapUI 產生報表來檢視：

1. 在左側 Navigator 窗格中選擇 TempConvertSoap 綁定，按滑鼠右鍵帶出功能列表並從中選

擇 Generate Documentation，擇定目錄後按 OK 進行儲存。

<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/"

xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"

xmlns:xsd="http://www.w3.org/2001/XMLSchema">

<soap:Body>

<FahrenheitToCelsiusResponse xmlns="https://www.w3schools.com/xml/">

<FahrenheitToCelsiusResult>100</FahrenheitToCelsiusResult>

</FahrenheitToCelsiusResponse>

</soap:Body>

</soap:Envelope>

2. 報表會以 HTML 格式儲存，且儲存後 SoapUI 應該會開啟瀏覽器來顯示內容。若發現未

自動開啟，也可以至儲存目錄內點擊該檔案開啟。

3. 從其中挑選要使用的對象(FahrenheitToCelsius)後按選 Detail。

4. 瀏覽器會跳到該對象的描述內容：

從中可以得知相關變數在伺服器端的宣告型態(在範例中，Fahrenheit 宣告為 string)。

5. 依照該型態決定 COBOL 程式的定義內容，變數長度可自行依預計範圍來定。


03 Fahrenheit pic x(3) value zeros.

而回應部份，則可以依照相同的程序進行處理： <FahrenheitToCelsiusResponse xmlns="https://www.w3schools.com/xml/">

<FahrenheitToCelsiusResult>100</FahrenheitToCelsiusResult>

</FahrenheitToCelsiusResponse>

可以對應成

01 Fahrenheit-To-Celsius-Response.

03 Fahrenheit-To-Celsius-Result pic X(10).

建立提供給 XML Extensions 使用的 XSLT 樣式表

在 SoapUI 開啟且先前對 FahrenheitToCelcius 請求與回應的 XMLs 皆存在的情況下，新增一個

資料匣用來放置本篇處理範例的資源。

開啟自己常用(或簡易)的文字編輯器。從 SoapUI 將請求的 XML 複製到編輯器內並儲存起來，

將其命名為 TempConvertRequestF2C.xsl 並置於先前建立的資料匣內(相較於用按滑鼠右鍵帶出

選單並選擇“Save As…”會少了開頭的 <?xml version="1.0" encoding="UTF-8"?> 內容)。同時也

將回應的 XML 進行同樣的處理，並將其命名為 TempConvertResponseF2C.xsl 並也置於先前建

立的資料匣內。(檔案名稱可以自訂，但是之後的 COBOL 程式中使用 XML Extensions 的時候也

要對應調整引用的 XSLT 檔名。)

為了要決定是否需要 SOAPAction 這個 HTTP 的綁定參數，按一下在 SoapUI Project 瀏覽窗格

內的 FahrenheitToCelsius 綁定項目來顯示在底下的 Operation Properties 窗格。在窗格中會顯

示存在於 WSDL 內的參數，如果在其中的 SOAPAction 屬性包含有設定值，該值會在要進行

SOAP 請求時使用。在稍後的步驟會需要在程式中進行編寫(變數的宣告)，所以先進行一下註

記：

SOAPAction 參數是 SOAP 1.1 與 SOAP 1.2 Web 服務定義中非必要的部分，但它位於 HTTP 標頭

可以協助 Web 伺服器決定 SOAP 請求的型態，而不需調查整個 XML 的內容。

在這一階段儲存的檔案，雖然副檔名為 XSL，不過內容尚不是正確的 XSLT 格式，在可提供給

XML Extensions 使用前必須先修改調整。調整的方向大概含有：

確認含有 XML 檔案開頭描述：<?xml version='1.0' ?>

加入<xsl:stylesheet>部份，定義樣式表的 root 元素。

可加入<xsl:template>部份，建構模版定義。

以<xsl:value-of>取代變數值的部份

如果讀者與筆者相同，對於 XSLT 不是那麼瞭解而無法自行調整(撰寫)其內容，那麼可以採取

與筆者相同的方式 – 套用樣板模型；這適用於簡易的轉換過濾內容。

以請求的部份來說，基本樣版類似如下：

針對請求時會需要用到的 TempConvertRequestF2C.xsl，調整後會成為以下的建議內容(增加的

<?xml version='1.0' ?>

<xsl:stylesheet version="1.0" xmlns:xsl="http://www.w3.org/1999/XSL/Transform">

<xsl:output method="xml" encoding="UTF-8" indent="yes"/>

<xsl:template match="/">

... (預計填入先前從 SoapUI儲存的請求 XML內容，應該需要少量的調整與修改)

</xsl:template>

</xsl:stylesheet>

部份以粗體字呈現，因為排版關係採自動換行)：

因為是要從 COBOL 變數轉成 XML，所以 xsl:value-of select 後面所帶的內容是 COBOL 程式內的

變數宣告名稱，階層以“/”表示。而外部節點則是採用 prototype 中取得的服務變數名稱。

而解析回應內容時會用到的 XSLT 要考慮多一些，因為是要從 XML 內容轉換成 COBOL 變數的

內容，基本樣版類似如下：

而要填入的部份，相對的節點需採用 COBOL 程式宣告的變數名稱，關於在主體中 xsl:value-of

select 所帶的變數名稱則轉變為 Web 服務傳回時在 XML 中所使用的變數名稱。因此整個 XSLT

調整成以下的建議內容：


<xsl:stylesheet version="1.0" xmlns:xsl="http://www.w3.org/1999/XSL/Transform">

<xsl:output method="xml" encoding="UTF-8" indent="yes"/>


<soapenv:Envelope xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"

xmlns:xsd="http://www.w3.org/2001/XMLSchema"

xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"

xmlns:x="https://www.w3schools.com/xml/">

<soapenv:Body>


<x:Fahrenheit>

<xsl:value-of select="fahrenheit-to-celsius/fahrenheit"/>

</x:Fahrenheit>


</soapenv:Body>

</soapenv:Envelope>

</xsl:template>

</xsl:stylesheet>


<xsl:stylesheet version="1.0" xmlns:xsl="http://www.w3.org/1999/XSL/Transform"

xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/" xmlns:a="Web服務所在的網址">

<xsl:output method="html" encoding="UTF-8" indent="yes"/>


... (預計填入先前儲存的 XML回應對應到 COBOL變數宣告的內容，應該需要較多的調整與修改)

</xsl:template>

</xsl:stylesheet>

建立 Web 服務客戶端 COBOL 程式

預備好相關變數定義與所需使用的檔案後，在 COBOL 程式內就加入相關的處理邏輯。在此列

出幾個必要的部份。

首先在接收到要傳送給 Web 服務的華氏溫度數值後，需要將其轉成 XML 文件內容，可以透

過下列的 XML Extension 敘述內容產生出 SOAP envelop(request-payload)：

執行後，請求的內容會正確的格式化，接下來就可以交給 RMNet 送出請求給 Web 服務，簡

單的敘述寫法如下：

其中有一個 Desired-SOAP-Action 的變數，在之前的處理中已得知 SOAPAction 的值，所以按照


<xsl:stylesheet version="1.0" xmlns:xsl="http://www.w3.org/1999/XSL/Transform"

xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/"

xmlns:a="https://www.w3schools.com/xml/">

<xsl:output method="html" encoding="UTF-8" indent="yes"/>


<Fahrenheit-To-Celsius-Response>

<Fahrenheit-To-Celsius-Result>

<xsl:value-of select="//a:FahrenheitToCelsiusResult"/>

</Fahrenheit-To-Celsius-Result>

</Fahrenheit-To-Celsius-Response>

</xsl:template>

</xsl:stylesheet>

call "NetInit"

giving response-status.

call "HttpPost"

using

Post-Address || Web服務 URL

Content-Type || 描述 MIME型態與字元編碼(encoding)格式

request-payload

request-len

response-payload

response-len

Desired-SOAP-Action

giving response-status.

XML EXPORT TEXT

Fahrenheit-To-Celsius

request-payload

request-len

"Fahrenheit-To-Celsius"

"TempConvertRequestF2C.xsl".

if not XML-OK perform Exit-Client-Program.

API 的規範將其定義如下：

01 Desired-SOAP-Action.

05 filler pic x(10) value 'SOAPAction'.

05 filler pic x value x"00".

05 filler pic x(90) value

'"https://www.w3schools.com/xml/FahrenheitToCelsius"'.


執行後如果成功，在參數中的 response-payload 就包含了 Web 服務的 XML 內容，接下來就準

備利用 XML Extensions 再將內容結果導出給 COBOL 資料變數。

如果該 Web 服務的網站是採用安全協定來傳輸，那麼需要在呼叫 HttpPost 之前設定使用提供

的憑證，使用指令如下：

“ca-bundle.crt”為手上持有的憑證檔名。

而當呼叫 HttpPost 時有發生錯誤，可以接著呼叫 NetGetError 來取得錯誤的訊息內容：

在其中有一個一般 COBOL 程式員較少用到的寫法：

set address of http-response to response-payload.

當呼叫 NetGetError 時會帶入一個 response-payload 的參數來準備儲存內容，其資料型態需

要宣告為：pointer，也就是在 Working-Storage 內會有這樣一行變數的宣告：

01 response-payload usage pointer.

它是一個位址指標，內容並非直接擺存回應的文字內容，所以我們需要另外再宣告一個文數

字型態的變數“結合”到指標變數，這就是 set address of … to … 這行指令在進行的動作。也因

為這指令的使用條件，我們需要將文數字型態的變數宣告在 linkage section 內：

call "NetSetSSLCA" using "ca-bundle.crt".

if not response-status = 0

call "NetGetError" using response-payload response-len

giving response-status-2

set address of http-response to response-payload

display "Error! ", response-status

display "Error message: ", http-response(1:response-len)

call "NetFree" using response-payload

accept omitted

perform Exit-Client-Program

end-if.

這樣的程式寫法可以說是含有 set address of 指令的特例，與一般 COBOL 程式的認知不同，

執行時並不需要由別支 COBOL 程式來進行呼叫。這算是 ACUCOBOL-GT 要與外界 C 程式進行

參數溝通的一種用法。

最後這支 Web 服務的用戶端程式需要將得到的回應內容以 XML Extensions 導出給 COBOL 變

數：

執行成功後就可以對 COBOL 變數內的值進行處理，譬如顯示在畫面上或是其它用途。在完成

整個動作後，就是一支簡易的呼叫 Web 服務的 COBOL 程式。以下是筆者測試用的 COBOL 範

例： IDENTIFICATION DIVISION.

PROGRAM-ID. tempconv.

DATA DIVISION.

WORKING-STORAGE SECTION.


03 Fahrenheit pic x(3) value zeros.

88 is-quit value spaces.

01 Fahrenheit-To-Celsius-Response.

03 Fahrenheit-To-Celsius-Result pic X(20).

copy "lixmlall.cpy".

01 request-payload usage pointer.

01 response-payload usage pointer.

01 response-status pic 9(3) value zero.

01 response-status-2 pic 9(3) value zero.

01 response-len pic s9(4).

01 request-len pic s9(4).

01 Desired-SOAP-Action.

05 filler pic x(10) value 'SOAPAction'.


05 filler pic x(90) value

'"https://www.w3schools.com/xml/FahrenheitToCelsius"'.


78 Post-Address value

"https://www.w3schools.com/xml/tempconvert.asmx".

78 Content-Type value "text/xml; charset=utf-8".

LINKAGE SECTION.

01 http-response pic x(100).

******************************************************************

PROCEDURE DIVISION.

Main Section.

Perform initial-env.

LINKAGE SECTION.

01 http-response pic x(100).

XML IMPORT TEXT

Fahrenheit-To-Celsius-Response

response-payload

response-len

"Fahrenheit-To-Celsius-Response"

"TempConvertResponseF2C.xsl".


with test after

until (Fahrenheit(1:1) is numeric or

Fahrenheit(1:1) = "-") and

Fahrenheit(2:) is numeric

accept Fahrenheit, line 5, column 16,

prompt, update,

control "upper"

if is-quit


end-if

end-perform.

perform prepare-request.

perform do-request.

perform process-response.

display " Celsius: ", line 10 column 5

Fahrenheit-To-Celsius-Result.

accept omitted

perform Exit-Client-Program.

Library-Routines Section.

* Library Routines Description

initial-env.

XML INITIALIZE.

Exit-Client-Program.

XML TERMINATE.

Perform Display-XML-Status.

Exit Program.

Stop Run.

prepare-request.

XML EXPORT TEXT

Fahrenheit-To-Celsius

request-payload

request-len

"Fahrenheit-To-Celsius"

"TempConvertRequestF2C.xsl".

do-request.

call "NetInit"

giving

response-status.

call "NetSetSSLCA" using "ca-bundle.crt".

call "HttpPost"

using

Post-Address

Content-Type

request-payload

request-len

response-payload

response-len

Desired-SOAP-Action

giving

response-status.

if not response-status = 0

call "NetGetError" using response-payload response-len

giving response-status-2

set address of http-response to response-payload

display "Error! ", response-status

display "Error message: ", http-response(1:response-len)

call "NetFree" using response-payload

accept omitted


end-if.

XML FREE TEXT

request-payload.

if response-payload = NULL

display "Error: NULL pointer returned", line 10, blink

accept omitted


end-if.

process-response.

XML IMPORT TEXT

Fahrenheit-To-Celsius-Response

response-payload

response-len

"Fahrenheit-To-Celsius-Response"

"TempConvertResponseF2C.xsl".


call "NetFree"

using

response-payload.

call "NetCleanup".

Display-XML-Status.

If Not XML-IsSuccess

Perform With Test After Until XML-NoMore

XML GET STATUS-TEXT

Display XML-StatusText

End-Perform

End-If.

編譯與執行 COBOL 程式

1. 在完成所有動作後，可以將相關檔案複製到一個自建的目錄中。

COBOL 程式(譬如命名為 tempconv.cbl)與所需要的 copy files

建立出來的 XSL 檔案

ca-bundle.crt (範例內使用的憑證檔名稱，有需要時需複製到目錄中)

2. 進行程式編譯(在 Windows 環境中，通常編譯器名稱為 ccbl32；而 UNIX/Linux 則是 ccbl。

請在使用時自行轉換為可用程式名)。

ccbl32 -Sr -Ze tempconv.cbl

3. 編譯完成後就可以準備執行程式(在 Windows 環境中，通常編譯器名稱為 wrun32；而

UNIX/Linux 則是 runcbl。請在使用時自行轉換為可用程式名)。因為程式中會用到 RMNet

與 XML Extensions，要執行程式時，需要設定載入這兩者所需的外部 libraries：rmnet.dll

& xmlif.dll (在 Linux/UNIX 上則為 librmnet64.so & libxmlif64.so)

直接在命令列上指定：

wrun32 -y rmnet.dll -y xmlif.dll tempconv.acu

透過執行器 configuration 檔設定：在要使用的 configuration 檔(譬如 cblconfi)內加

入一行

SHARED_LIBRARY_LIST xmlif.dll rmnet.dll

再執行程式：wrun32 -c cblconfi tempconv.acu

4. 執行後，以筆者的範例中需要輸入 3 個數字，按下 Enter 後等候回應值(網路需開啟且可

連結到 https://www.w3school.com)。若不想執行而要離開，可以輸入 3 個空白後按下

Enter 鍵直接結束。

如有任何問題歡迎來電討論, TEL: (02) 2312-8866 廖先生

Documents

使用RMNet 呼叫Web 服務