PCML struct 標籤

PCML struct 標籤可以下列元素展開。

<struct name="name"
    [ count="{number | data-name }"]
    [ maxvrm="version-string" ]
    [ minvrm="version-string" ]
    [ offset="{number | data-name }" ]
    [ offsetfrom="{number | data-name | struct-name }" ]
    [ outputsize="{number | data-name }" ]
    [ usage="{ inherit | input | output | inputoutput }" ]>
</struct>

以下表格列出 struct 標籤的屬性。每個項目都包括屬性名稱、可能的有效值和屬性的說明。

屬性 值 說明
name= name 指定 <struct> 元素的名稱
count= number，其中 number 定義固定、永不變更大小的陣列。

data-name， 其中 data-name 定義 PCML 文件中的 <data> 元素名稱，在執行時間，該元素會包含陣列中的元素數目。 指定的 data-name 可以是完整名稱，或是現行元素的相對名稱。不論是哪一種情況，名稱都必須參照以 type="int" 定義的 <data> 元素。 如需相對名稱的解析方式詳細資訊，請參閱解析相對名稱。

 指定元素是一個陣列，且識別陣列中的登錄數目。

如果略過這個屬性，則元素雖然不會定義為陣列，但它可能包含在定義為陣列的另一個元素內。
maxvrm= version-string 指定元素所在處的最高 IBM® i 版本。如果 IBM i 版本高於屬性上指定的版本，則在呼叫程式期間，將不會處理元素及其子項（如果有的話）。maxvrm 元素有助於定義 IBM i 版次之間不同的程式介面。

版本字串的語法必須是 "VvRrMm"，其中大寫字母 "V"、"R" 及 "M" 是文字字元，而 "v"、"r" 及 "m" 則是代表版本、 版次及修正層次的數字（一或多位數）。"v" 的值必須是從 1 到 255。"r" 及 "m" 的值必須是從 0 到 255。
minvrm= version-string 指定此元素所在處的最低 IBM i 版本。如果 IBM i 版本低於此屬性上指定的版本，則在呼叫程式期間，將不會處理此元素及其子項（如果有的話）。此屬性有助於定義不同 IBM i 版次之間的程式介面。

版本字串的語法必須是 "VvRrMm"，其中大寫字母 "V"、"R" 及 "M" 是文字字元，而 "v"、"r" 及 "m" 則是代表版本、 版次及修正層次的數字（一或多位數）。"v" 的值必須是從 1 到 255。"r" 及 "m" 的值必須是從 0 到 255。
offset= number，其中 number 定義固定、永不變更的偏移。

data-name，其中 data-name 定義 PCML 文件中的 <data> 元素名稱，在執行時間，該元素將會包含元素的偏移。 指定的 data-name 可以是完整名稱，或是現行元素的相對名稱。不論是哪一種情況，名稱都必須參照以 type="int" 定義的 <data> 元素。 如需相對名稱的解析方式詳細資訊，請參閱解析相對名稱。

 指定輸出參數內的 <struct> 元素的偏移。

有些程式會傳回具有固定結構的資訊，其後跟著一個或多個可變長度欄位或結構。在這種情況下， 可變長度元素的位置，通常指定為參數內的偏移或位移。offset 屬性會用來說明此 <struct> 元素的偏移。

Offset 將結合 offsetfrom 屬性一起使用。 如果未指定 offsetfrom 屬性，則 offset 屬性上指定的偏移的基本位置將是元素的母項。如需如何使用 offset 及 offsetfrom 屬性的相關資訊，請參閱指定偏移。

offset 與 offsetfrom 屬性僅會用來 處理來自程式的輸出資料。這些屬性不會控制輸入資料的偏移或位移。

如果略過屬性，則元素的資料位置之後緊跟著參數中的前一個元素，若有的話。
offsetfrom= number，其中 number 定義固定、永不變更的基本位置。number 屬性 最常用來指定 number="0"，表示偏移 是從參數開頭開始的絕對偏移。

data-name，其中 data-name 定義 <data> 元素的名稱，此元素會作為偏移的基本位置。 指定的元素名稱必須是這個元素的母項或祖先項。來自 offset 屬性的值，將相對於此屬性上指定元素的位置。指定的 data-name 可以是完整名稱，或是現行元素的相對名稱。 不管哪一種情況，名稱必須參照這個元素的祖先項。如需相對名稱的解析方式詳細資訊，請參閱解析相對名稱。

struct-name，其中 struct-name 定義 <struct> 元素的名稱，此元素會作為偏移的基本位置。指定的元素名稱必須是這個元素的母項或祖先項。來自 offset 屬性的值，將相對於此屬性上指定元素的位置。 指定的 struct-name 可為完整的名稱或是與現行元素相對的名稱。 不管哪一種情況，名稱必須參照這個元素的祖先項。如需相對名稱的解析方式詳細資訊，請參閱解析相對名稱。

 指定與 offset 屬性相對的基本位置。

如果未指定 offsetfrom 屬性，則 offset 屬性上指定的偏移基本位置即為這個元素的母項。如需如何使用 offset 及 offsetfrom 屬性的相關資訊，請參閱指定偏移。

offset 與 offsetfrom 屬性僅會用來 處理來自程式的輸出資料。這些屬性不會控制輸入資料的偏移或位移。
outputsize= number，其中 number 會定義要保留的固定、永不變更的位元組數目。

data-name， 其中 data-name 定義 PCML 文件中的 <data> 元素名稱，在執行時間，該元素會包含要為輸出資料保留的位元組數。 指定的 data-name 可以是完整名稱，或是現行元素的相對名稱。不論是哪一種情況，名稱都必須參照以 type="int" 定義的 <data> 元素。 如需相對名稱的解析方式詳細資訊，請參閱解析相對名稱。

 指定要保留給元素的輸出資料的位元組數目。對長度可變的輸出參數而言，必須要有 outputsize 屬性， 才能指定須保留多少個位元組讓將要從伺服器程式傳回的資料使用。Outputsize 可以在所有可變長度欄位及可變大小陣列上指定，或它可以針對含有一個或多個可變長度欄位的整個參數而指定。

沒有必要針對固定大小輸出參數指定 Outputsize， 就算有必要也不得指定。

屬性上指定的值將作為元素的總大小，包括元素的所有子項。因此，在元素的任何子項或後代項上，不會處理 outputsize 屬性。

如果省略屬性，則要保留給輸出資料的位元組數，是在執行時間將要為 <struct> 元素的所有子項保留的位元組數加在一起來決定。
usage= inherit 用法將繼承自母項元素。如果結構沒有母項，則用法將假設為 inputoutput。
input 結構是主程式的輸入值。對於字元與數字類型，將執行適當的轉換。
output 結構是主程式的輸出值。對於字元與數字類型，將執行適當的轉換。
inputoutput 結構同時為輸入及輸出值。

指定偏移

有些程式會傳回具有固定結構的資訊，其後跟著一個或多個可變長度欄位或結構。在這種情況下， 可變長度元素的位置，通常指定為參數內的偏移或位移。

偏移即是從參數開頭到欄位或結構開頭的距離，以位元組表示。 位移即是從某個結構的開頭到另一結構開頭的距離，以位元組表示。

對於偏移， 因為距離是從參數開頭開始算起，所以請指定 offsetfrom="0"。 下列是從參數開頭開始算起的偏移的範例：

<pcml version="1.0">
  <program name="myprog" path="/QSYS.lib/MYLIB.lib/MYPROG.pgm">
    <!-- receiver variable contains a path -->
    <struct name="receiver" usage="output" outputsize="2048">
      <data name="pathType"         type="int"  length="4" />
      <data name="offsetToPathName" type="int"  length="4" />
      <data name="lengthOfPathName" type="int"  length="4" />
      <data name="pathName"         type="char" length="lengthOfPathName"
               offset="offsetToPathName"  offsetfrom="0"/>
    </struct>
  </program>
</pcml>

對於位移，因為距離是從另一個結構開始算起，所以您可以指定與偏移相對的結構的名稱。下列是從已命名的結構開頭開始算起的位移的範例：

<pcml ="1.0">
  <program name="myprog" path="/QSYS.lib/MYLIB.lib/MYPROG.pgm">
    <!-- receiver variable contains an object -->
    <struct name="receiver" usage="output" >
      <data name="objectName"       type="char"  length="10" />
      <data name="libraryName"      type="char"  length="10" />
      <data name="objectType"       type="char"  length="10" />
      <struct name="pathInfo" usage="output" outputsize="2048" >
        <data name="pathType"         type="int"  length="4" />
        <data name="offsetToPathName" type="int"  length="4" />
        <data name="lengthOfPathName" type="int"  length="4" />
        <data name="pathName"         type="char" length="lengthOfPathName"
                 offset="offsetToPathName"  offsetfrom="pathInfo"/>
      </struct>
    </struct>
  </program>
</pcml>
上層主題: PCML 語法