PCML struct tag

The PCML struct tag can be expanded with the following elements.

<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>

The following table lists the struct tag attributes. Each entry includes the attribute name, the possible valid values, and a description of the attribute.

Attribute Value Description
name= name Specifies the name of the <struct> element
count= number where number defines a fixed, never-changing sized array.

data-name where data-name defines the name of a <data> element within the PCML document that will contain, at runtime, the number of elements in the array. The data-name specified can be a fully qualified name or a name that is relative to the current element. In either case, the name must reference a <data> element that is defined with type="int". See Resolving Relative Names for more information about how relative names are resolved.

 Specifies that the element is an array and identifies the number of entries in the array.

If this attribute is omitted, the element is not defined as an array, although it may be contained within another element that is defined as an array.
maxvrm= version-string Specifies the highest version of IBM® i on which the element exists. If the version of IBM i is greater than the version specified on the attribute, the element and its children, if any exist, will not be processed during a call to a program. The maxvrm element is helpful for defining program interfaces which differ between releases ofIBM i.

The syntax of the version string must be "VvRrMm," where the capitals letters "V," "R," and "M" are literal characters and "v," "r," and "m" are one or more digits representing the version, release and modification level. The value for "v" must be from 1 to 255 inclusively. The value for "r" and "m" must be from 0 to 255, inclusively.
minvrm= version-string Specifies the lowest version of IBM i on which this element exists. If the version of IBM i is less than the version specified on this attribute, this element and its children, if any exist, will not be processed during a call to a program. This attribute is helpful for defining program interfaces which differ between releases of IBM i.

The syntax of the version string must be "VvRrMm," where the capitals letters "V," "R," and "M" are literal characters and "v," "r," and "m" are one or more digits representing the version, release and modification level. The value for "v" must be from 1 to 255, inclusively. The value for "r" and "m" must be from 0 to 255, inclusively.
offset= number where number defines a fixed, never-changing offset.

data-name where data-name defines the name of a <data> element within the PCML document that will contain, at runtime, the offset to the element. The data-name specified can be a fully qualified name or a name that is relative to the current element. In either case, the name must reference a <data> element that is defined with type="int". See Resolving Relative Names for more information about how relative names are resolved.

 Specifies the offset to the <struct> element within an output parameter.

Some programs return information with a fixed structure followed by one or more variable length fields or structures. In this case, the location of a variable length element is typically specified as an offset or displacement within the parameter. The offset attribute is used to describe the offset to this <struct> element.

Offset is used in conjunction with the offsetfrom attribute. If the offsetfrom attribute is not specified, the base location for the offset specified on the offset attribute is the parent of the element. See Specifying Offsets for more information about how to use the offset and offsetfrom attributes.

The offset and offsetfrom attributes are only used to process output data from a program. These attributes do not control the offset or displacement of input data.

If the attribute is omitted, the location of the data for the element is immediately following the preceding element in the parameter, if any.
offsetfrom= number where number defines a fixed, never-changing base location. A number attribute is most typically used to specify number="0" indicating that the offset is an absolute offset from the beginning of the parameter.

data-name where data-name defines the name of a <data> element to be used as a base location for the offset. The element name specified must be the parent or an ancestor of this element. The value from the offset attribute will be relative to the location of the element specified on this attribute. The data-name specified can be a fully qualified name or a name that is relative to the current element. In either case, the name must reference an ancestor of this element. See Resolving Relative Names for more information about how relative names are resolved.

struct-name where struct-name defines the name of a <struct> element to be used as a base location for the offset. The element name specified must be the parent or an ancestor of this element. The value from the offset attribute will be relative to the location of the element specified on this attribute. The struct-name specified can be a fully qualified name or a name that is relative to the current element. In either case, the name must reference an ancestor of this element. See Resolving Relative Names for more information about how relative names are resolved.

 Specifies the base location from which the offset attribute is relative.

If the offsetfrom attribute is not specified, the base location for the offset specified on the offset attribute is the parent of this element. See Specifying Offsets for more information about how to use the offset and offsetfrom attributes.

The offset and offsetfrom attributes are only used to process output data from a program. These attributes do not control the offset or displacement of input data.
outputsize= number where number defines a fixed,never-changing number of bytes to reserve.

data-name where data-name defines the name of a <data> element within the PCML document that will contain, at runtime, the number of bytes to reserve for output data. The data-name specified can be a fully qualified name or a name that is relative to the current element. In either case, the name must reference a <data> element that is defined with type="int". See Resolving Relative Names for more information about how relative names are resolved.

 Specifies the number of bytes to reserve for output data for the element. For output parameters which are variable in length, the outputsize attribute is needed to specify how many bytes must be reserved for data to be returned from the server program. Outputsize can be specified on all variable length fields and variable sized arrays, or it can be specified for an entire parameter that contains one or more variable length fields.

Outputsize is not necessary and must not be specified for fixed-size output parameters.

The value specified on the attribute is used as the total size for the element including all children of the element. Therefore, the outputsize attribute is ignored on any children or descendants of the element.

If the attribute is omitted, the number of bytes to reserve for output data is determined at runtime by adding the number of bytes to reserve for all of the children of the <struct> element.
usage= inherit Usage is inherited from the parent element. If the structure does not have a parent, usage is assumed to be inputoutput.
input The structure is an input value to the host program. For character and numeric types, the appropriate conversion is performed.
output The structure is an output value from the host program. For character and numeric types, the appropriate conversion is performed.
inputoutput The structure is both and input and an output value.

Specifying offsets

Some programs return information with a fixed structure followed by one or more variable length fields or structures. In this case, the location of a variable length element is typically specified as an offset or displacement within the parameter.

An offset is the distance in bytes from a the beginning of the parameters to the beginning of a field or structure. A displacement is the distance in bytes from the beginning of one structure to the beginning of another structure.

For offsets, since the distance is from the beginning of the parameter, specify offsetfrom="0". The following is an example of an offset from the beginning of the parameter:

<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>

For displacements, since the distance is from the beginning of another structure, you specify the name of the structure to which the offset is relative. The following is an example of an displacement from the beginning of a named structure:

<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>
Parent topic: PCML syntax