XML-INTO (將 XML 文件剖析成變數)

開放式語法

XML-INTO{(EH)} 接收端 %XML (xmlDoc {: options });

XML-INTO{(EH)} %HANDLER (handlerProc : commArea) %XML (xmlDoc {: options });

代碼	因素1	擴充因素2
XML-INTO		receiver %XML (xmlDoc {: options })
XML-INTO		%HANDLER (handlerProc : commArea) %XML (xmlDoc {: options })

提示: 如果您不熟悉 XML 及處理 XML 文件的基本概念，您可能會發現閱讀 Rational® Development Studio for i中的「處理 XML 文件」一節很有用: 在此章節中進一步閱讀之前，請先閱讀 ILE RPG Programmer 's Guide 。

XML-INTO 有兩種不同的運作方式:

將 XML 資料直接讀取至 RPG 變數
將 XML 資料逐漸讀入陣列參數，並傳遞至 %HANDLER 指定的程序 (handlerProc)。

第一個運算元指定已剖析資料的目標。它可以包含變數名稱或 %HANDLER 內建函數。

第二個運算元必須是 %XML 內建函數，用於識別要剖析的 XML 文件以及控制剖析方式的選項。如需 %XML 的相關資訊，請參閱 %XML (xmlDocument {:options}) 。

如果第一個運算元是變數名稱:

將直接在變數中執行剖析。
變數名稱將用來建立要剖析的 XML 元素名稱; 這可以使用路徑選項來置換。
如果變數是資料結構，則部分子欄位可能由作業設定，即使作業因錯誤而結束也一樣。
如果變數是陣列，則剖析只會搜尋陣列中適合的資料。 PSDS 位置 372-379 中的「XML 元素數」子欄位將設為作業順利設定的元素數。對於資料結構陣列，如果在剖析元素子欄位的資料時發生剖析錯誤，則此值將不包括所設定的元素; 不過，此陣列元素可能具有作業所設定的部分子欄位。

如果第一個運算元是 %HANDLER 內建函數:

當剖析器已剖析足夠的 XML 資料來填入程序所處理的 RPG 陣列元素指定數目時，將會呼叫指定為 %HANDLER 第一個運算元的程序。當處理程式返回時，剖析器將繼續剖析 XML 資料，直到它已剖析足夠的 XML 資料，以再次填入指定數目的陣列元素來呼叫處理程序。這會繼續直到文件完全剖析，或直到程序傳回回覆碼指出剖析應該中止為止。
處理程序的最終呼叫可能比處理程序所能處理的 RPG 陣列元素更少。處理程序應該一律參照 "number of elements" 參數，以確保它不會存取沒有任何 XML 資料的陣列元素。

剖析器會將指定為 %HANDLER 的第二個運算元的通訊區變數作為第一個參數傳遞至處理程序，容許程序編碼 XML-INTO 作業與處理程序通訊，並容許處理程序將資訊從一個呼叫儲存至下一個呼叫。
在從 XML 資料載入之前，用來保留程序之陣列參數的臨時變數的每一個元素都將清除為其預設值。
path 選項必須用來指定要搜尋的 XML 元素名稱。請參閱 %DATA and %XML options for DATA-GEN ， DATA-INTO ，及 XML-INTO 和預期的 XML 資料格式，以及 path 選項的相關資訊。

在 XML-INTO 作業期間，可能會多次呼叫陣列處理程序。當剖析器在第二個參數上找到 DIM 關鍵字指定的元素數目時，將會呼叫程序。最後一次呼叫程序的元素可能少於 DIM 關鍵字指定的元素。如果找不到任何元素，則不會呼叫程序。

處理程序必須具有下列參數及傳回類型:

參數號碼或回覆值	資料類型及傳遞模式	說明
返回值	4 位元組整數 (10I 0)	傳回零值表示剖析應繼續進行; 傳回任何其他值表示剖析應結束。
1	任何類型，依參照傳遞	用來在 XML-INTO 作業與處理程式之間進行通訊，以及在對處理程式的連續呼叫之間進行通訊。
2	唯讀參照所傳遞的陣列或資料結構陣列 (CONST 關鍵字)	陣列元素包含 path 選項所指定 XML 元素中的資料。
3	4 位元組無正負號 (10U 0) ，依值傳遞	第二個參數中代表 XML 資料的陣列元素數目。

如需 %HANDLER 的相關資訊，請參閱 %handler (handlingProcedure : communicationArea ) 。

資料結構的子欄位將以它們在 XML 文件中出現的順序來設定; 如果子欄位在資料結構內重疊，則順序可能很重要。

在 XML-INTO 作業期間，未更新任何欄位或子欄位的 %NULLIND。

可指定作業擴充元 H ，以將數值資料指定為半調整。可指定作業擴充元 E 來處理下列狀態碼:

00351: XML 剖析時發生錯誤
00352: XML 選項無效
00353: XML 文件不符合 RPG 變數
00354: 準備 XML 剖析時發生錯誤

附註: 只有在使用開放式語法時，才能指定作業延伸器。

對於狀態 00351 ，剖析器的回覆碼將放置在 PSDS 的位置 368-371 的子欄位「外部回覆碼」中。此子欄位將在作業開始時設為零，並在作業結束時設為剖析器傳回的值。

如果在 %XML 內建函數的 options 參數中找到不明、無效或不相關的選項，則作業會失敗，狀態碼為 00352 (XML 選項中的錯誤)。當作業開始時，將不會從起始值零中更新 PSDS 中的外部回覆碼子欄位。

XML 文件預期符合 RPG 變數的 XML 元素或屬性名稱。

RPG 資料結構的 XML 資料預期具有與資料結構同名的 XML 元素，以及與 RPG 子欄位同名的子元素及/或屬性。
RPG 陣列的 XML 資料預期具有一系列與 RPG 陣列同名的元素。

path 選項可用來設定符合指定變數名稱的 XML 元素名稱，但無法用來設定符合指定變數子欄位之 XML 元素及/或屬性的名稱。例如，如果變數 DS1 具有子欄位 SF1，則 DS1 的 XML 元素可以具有任何名稱，但 SF1 的 XML 元素或屬性必須具有名稱 "sf1" (或 "SF1"，"Sf1" 等，視 case 選項而定)。

當 RPG 變數是資料結構的陣列或陣列時，或當指定 %HANDLER 內建函數時，預期對應於陣列元素的 XML 元素會包含在另一個 XML 元素中。依預設， XML 元素將預期為文件中最外層 XML 元素的子元素。 path 選項可用來指定對應於陣列元素之 XML 元素的確切路徑。例如，如果最外層 XML 元素命名為 "transaction" ，且它有一個名為 "parts" 的子元素，其本身有數個名為 "part" 的子元素，則若要將 "part" XML 元素讀入陣列中，您可以指定選項 'path=transaction/parts/part'。

  <transaction>
    <parts>
       <part type = "bracket" size="15" num="100"/>
       <part type="frame" size="2" num="500"/>
    </parts>
  <transaction>

當 XML 文件不符合 RPG 變數時，例如，如果 XML 文件不包含預設或指定的路徑，或如果它遺漏部分 XML 元素或屬性以符合 RPG 資料結構的子欄位，則 XML-INTO 作業會失敗，狀態為 00353。 allowextra 和 allowmissing 選項可用來指定 XML 元素的資料是否比完整設定 RPG 變數所需的資料多或少。

對於部分 RPG 資料類型，可以指定 XML 屬性，以控制如何將 XML 資料指派給 RPG 變數。如需這些屬性的相關資訊，請參閱將資料傳送至 XML-INTO 及 DATA-INTO 的 RPG 變數的規則。

If an XML reference other than the predefined references &amp, &apos, &lt, &gt, &quot, or the hexadecimal unicode references &#xxxx is found, the result will contain the reference itself, in the form "&refname;". 如果此值對資料類型無效，則作業會失敗。例如，如果 XML 元素具有值 <data>1&decpoint;50/data> ，則會從三個片段 "1"、 "&decpoint;"及 "0" 建置字串 "1&decpoint;50"。此資料適用於字元或 UCS-2 變數，但如果轉換為其他類型，則會導致錯誤。

提示: 如果已知 XML 資料包含此類參照，則在 XML-INTO 作業完成之後，應該檢查字元及 UCS-2 資料是否存在參照，以及使用字串作業 (例如 %SCANRPL 或 %SCAN 及 %REPLACE) 替代參照的正確值。

如果 XML 資料對其相符的 RPG 變數類型無效，則作業會失敗，狀態為 0353; 指派錯誤的特定狀態碼會出現在訊息 RNX0353的取代文字中。

提示: 若要避免 XML-INTO 作業失敗，因為資料無法順利指派給類型為「日期」或「數值」的 RPG 欄位，可以使用所有類型為字元或 UCS-2的子欄位來定義接收端變數。然後， RPG 程式可以使用轉換內建函數 %DATE、%INT 等，將資料轉換為其他資料類型。

XML-INTO 作業會忽略 DOCTYPE 宣告。 DOCTYPE 宣告可能包含您程式必須手動處理的實體參照值。如果您想要存取 XML 文件的 DOCTYPE 宣告，您可以使用 XML-SAX 作業。您的 XML-SAX 處理程序只要找到 DOCTYPE 宣告值，或只要知道沒有 DOCTYPE 宣告，就可以停止剖析。

下列鏈結提供 XML-INTO 的相關資訊。