The data tag

The data tag can have the following attributes. Attributes enclosed in brackets, [], indicate that the attribute is optional. If you specify an optional attribute, do not include the brackets in your source. Some attribute values are shown as a list of choices enclosed in braces, {}, with possible choices separated by vertical bars, |. When you specify one of these attributes, do not include the braces in your source and only specify one of the choices shown.
<data type="{ char | int | packed | zoned | float | byte | struct }"
Begin change   [ bidistringtype="{ ST4 | ST5 | ST6 | ST7 | ST8 | ST9 | ST10 | ST11 | DEFAULT }"]End change
    [ ccsid="{ number | data-name }" ]
    [ count="{ number | data-name }" ]
    [ init="string" ]
    [ length="{ number | data-name }" ]
    [ maxvrm="version-string" ]
    [ minvrm="version-string" ]
    [ name="name" ]
    [ offset="{ number | data-name }" ]
    [ offsetfrom="{ number | data-name | struct-name }" ]
    [ outputsize="{ number | data-name | struct-name }" ]
    [ passby= "{ reference | value }" ]
    [ precision="number" ]
    [ struct="struct-name" ]
    [ usage="{ inherit | input | output | inputoutput }" ]>
</data>
Attribute Value Description
type= char
where char indicates a character value. The length attribute specifies the number of bytes of data which may be different than the number of characters. A char data value is returned as a java.lang.String.

int
where int is an integer value. The length attribute specifies the number of bytes, "2" or "4". The precision attribute specifies the number of bits of precision. For example:

length="2" precision="15"
Specifies a 16-bit signed integer. An int data value with these specifications is returned as a java.lang.Short.
length="2" precision="16"
Specifies a 16-bit unsigned integer. An int data value with these specifications is returned as a java.lang.Integer.
length="4" precision="31"
Specifies a 32-bit signed integer. An int data value with these specifications is returned as a java.lang.Integer.
length="4" precision="32"
Specifies a 32-bit unsigned integer. An int data value is returned as a java.lang.Long.
Begin changelength="8" precision="63"
Specifies a 64-bit signed integer. An int data value is returned as a java.lang.Long.End change
 

For length="2", the default precision is "15". For length="4", the default precision is "31".

packed
where packed is a packed decimal value. The length attribute specifies the number of digits. The precision attribute specifies the number of decimal positions. A packed data value is returned as a java.math.BigDecimal.

zoned
where zoned is a zoned decimal value. The length attribute specifies the number of digits. The precision attribute specifies the number of decimal positions. A zoned data value is returned as a java.math.BigDecimal.

float
where float is a floating point value. The length attribute specifies the number of bytes, "4" or "8". For length="4", the float data value is returned as a java.lang.Float. For length="8", the float data value is returned as a java.lang.Double.

byte
where byte is a byte value. The length attribute specifies the number of bytes. No conversion is performed on the data. A byte data value is returned as an array of byte values (byte[]).

struct
where struct specifies the name of the <struct> element. A struct allows you to define a structure once and reuse it multiple times within the document. When type="struct", it is as if the structure specified appeared at this location in the document.

Indicates the type of data being used (character, integer, packed, zoned, floating point, byte, or struct).
Begin changebidistringtype=

DEFAULT
where DEFAULT is the default string type for non-bidirectional data (LTR).

ST4
where ST4 is String Type 4.

ST5
where ST5 is String Type 5.

ST6
where ST6 is String Type 6.

ST7
where ST7 is String Type 7.

ST8
where ST8 is String Type 8.

ST9
where ST9 is String Type 9.

ST10
where ST10 is String Type 10.

ST11
where ST11 is String Type 11.

Specifies the bidirectional string type for <data> elements with type="char". If this attribute is omitted, string type for this element is implied by the CCSID (whether explicitly specified or the default CCSID of the host environment).

String types are defined in the javadoc for the BidiStringType class.End change

ccsid= number
where number defines a fixed, never-changing CCSID.

data-name
where data-name defines the name that will contain, at runtime, the CCSID of the character 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 on how relative names are resolved.

Specifies the host Coded Character Set ID (CCSID) for character data for the <data> element. The ccsid attribute can be specified only for <data> elements with type="char".

If this attribute is omitted, character data for this element is assumed to be in the default CCSID of the host environment.

count= number
where number defines a fixed, never-changing number of elements in a 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 on how relative names are resolved.

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

If the count 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.

init= string Specifies an initial value for the <data> element. The init value is used if an initial value is not explicitly set by the application program when <data> elements with usage="input" or usage="inputoutput" are used.

The initial value specified is used to initialize scalar values. If the element is defined as an array or is contained within a structure defined as an array, the initial value specified is used as an initial value for all entries in the array.

length= number
where number defines a fixed, never-changing length.

data-name
where data-name defines the name of a <data> element within the PCML document that will contain, at runtime, the length. A data-name can be specified only for <data> elements with type="char" or type="byte". 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 on how relative names are resolved.

Specifies the length of the data element. Usage of this attribute varies depending on the data type.
Data Type Description
type="char" The length attribute specifies the number of bytes, of data for this element. Note that this is not necessarily the number of characters. A literal number or data-name must be specified.
type="int" The length attribute specifies the number of bytes of data for this element: "2", "4", or Begin change"8". End change The precision attribute is used to specify the number of bits of precision and indicates whether the integer is signed or unsigned. A literal number must be specified.
type="packed" or "zoned" The length attribute specifies the number of numeric digits of data for this element. The precision attribute is used to specify the number of decimal digits. A literal number must be specified.
type="float" The length attribute specifies the number of bytes, 4 or 8, of data for this element. A literal number must be specified.
type="byte" The length attribute specifies the number of bytes of data for this element. A literal number or data-name must be specified.
type="struct" The length attribute is not allowed.
maxvrm= version-string Specifies the highest version of iSeries on which this element exists. If the iSeries version is greater 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 iSeries.

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, respectively. 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 iSeries on which this element exists. If the iSeries version 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 iSeries.

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, respectively. The value for "v" must be from 1 to 255 inclusively. The value for "r" and "m" must be from 0 to 255, inclusively.

name= name Specifies the name of the <data> element.
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 this 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 on how relative names are resolved.

Specifies the offset to the <data> 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 usually specified as an offset or displacement within the parameter.

An offset attribute 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 this element. See Specifying Offsets for more information on 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 this attribute is omitted, the location of the data for this element is immediately following the preceding element in the parameter, if any.

offsetfrom= number
where number defines a fixed, never-changing base location. Number 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 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 on how relative names are resolved.

struct-name
where struct-name defines the name of a <struct> element 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 on 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 on 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 a 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 on 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 should be reserved for data to be returned from the iSeries program. An outputsize attribute 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 should not be specified for fixed-size output parameters.

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

If outputsize 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.

passby= reference
where reference indicates that the parameter will be passed by reference. When the program is called, the program will be passed a pointer to the parameter value.

value
where value indicates an integer value. This value is allowed only when
type= "int" and length="4" is specified.

Specifies whether the parameter is passed by reference or passed by value. This attribute is allowed only when this element is a child of a <program> element defining a service program call.
precision= number Specifies the number of bytes of precision for some numeric data types.
Data Type Description
type="int"
length="2"
Use precision="15" for a signed 2-byte integer. Use precision="16" for an unsigned 2-byte integer. The default value is "15".
type="int"
length="4"
Use precision="31" for a signed 4-byte integer. Use precision="32" for an unsigned 4-byte integer.
Begin changetype="int"
length="8"
Use precision="63" for a signed 8-byte integer.End change
type="packed" or "zoned" The precision specifies the number of decimal digits. The number specified must be greater than or equal to zero and less than or equal to the total number of digits specified on the length attribute.
struct= name Specifies the name of a <struct> element for the <data> element. A struct attribute can be specified only for <data> elements with type="struct".
usage= inherit Usage is inherited from the parent element. If the structure does not have a parent, usage is assumed to be inputoutput.
input Defines an input value to the host program. For character and numeric types, the appropriate conversion is performed.
output Defines an output value from the host program. For character and numeric types, the appropriate conversion is performed.
inputoutput Defines both and input and an output value.

Resolving relative names

Several attributes allow you to specify the name of another element, or tag, within the document as the attribute value. The name specified can be a name that is relative to the current tag.

Names are resolved by seeing if the name can be resolved as a child or descendent of the tag containing the current tag. If the name cannot be resolved at this level, the search continues with the next highest containing tag. This resolution must eventually result in a match of a tag that is contained by the <pcml> tag, in which case the name is considered to be an absolute name, not a relative name.

<pcml version="1.0">
  <program name="polytest" path="/QSYS.lib/MYLIB.lib/POLYTEST.pgm">
    <!-- Parameter 1 contains a count of polygoins along with an array of polygons -->
    <struct name="parm1" usage="inputoutput">
      <data name="nbrPolygons" type="int" length="4" init="5" />
      <!-- Each polygon contains a count of the number of points along with an array of points -->
      <struct name="polygon" count="nbrPolygons">
        <data name="nbrPoints" type="int" length="4" init="3" />
        <struct name="point" count="nbrPoints" >
          <data name="x" type="int" length="4" init="100" />
          <data name="y" type="int" length="4" init="200" />
        </struct>
      </struct>
    </struct>
  </program>
</pcml>

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 usually specified as an offset or displacement within the parameter.

An offset is the distance in bytes from the beginning of the parameters to the beginnings 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, you should 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 version="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>