The PCML 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 }" [ bidistringtype="{ ST4 | ST5 | ST6 | ST7 | ST8 | ST9 | ST10 | ST11 | DEFAULT }"] [ ccsid="{ number | data-name }" ][ chartype="{ onebyte | twobyte }"]
[ 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" ]
[ trim="{ right | left | both | none }" ]
[ usage="{ inherit | input | output | inputoutput }" ]> </data>
The following table lists the data tag attributes. Each entry includes the attribute name, the possible valid values, and a description of the attribute.
Attribute | Value | Description |
---|---|---|
type= | char where char indicates a character value. A char data value is returned as a java.lang.String. For more information, see the char values for length. int
zoned float byte struct |
Indicates the type of data being used (character, integer, packed, zoned, floating point, byte, or struct). Values for the length and precision attributes are different for different data types. For more information, see the Values for length and precision. |
bidistringtype= |
DEFAULT ST4 ST5 ST6 ST7 ST8 ST9 ST10 ST11 |
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. |
ccsid= | number where number defines a fixed, never-changing CCSID. data-name |
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. |
![]() |
onebyte twobyte When using chartype, the length="number" attribute specifies the number of characters, not the number of bytes. |
Specifies the size of each character.![]() |
count= | number where number defines a fixed, never-changing number of elements in a sized array. data-name |
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= | ![]() where number defines the number of bytes that the data requires. However, when using the chartype attribute, number specifies the number of characters, not the number of bytes. ![]() data-name |
Specifies the length of the data element. Usage of this attribute varies depending on the data type. For more information, see the Values for length and precision. |
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 |
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 struct-name |
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 |
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 |
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. For more information, see the Values for length and precision. |
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". |
![]() |
right left both none |
Specifies how to trim white space from character data.![]() |
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. |
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>