friedkiwi/ibm-information-center
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity
14ed2849c6
ibm-information-center/dist/eclipse/plugins/i5OS.ic.rzahh_5.4.0.1/pcmlsttg.htm

257 lines
17 KiB
HTML
Raw Normal View History

Add readme and dist folders
2024-04-02 14:02:31 +00:00
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE html
PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html lang="en-us" xml:lang="en-us">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<meta name="security" content="public" />
<meta name="Robots" content="index,follow" />
<meta http-equiv="PICS-Label" content='(PICS-1.1 "http://www.icra.org/ratingsv02.html" l gen true r (cz 1 lz 1 nz 1 oz 1 vz 1) "http://www.rsac.org/ratingsv01.html" l gen true r (n 0 s 0 v 0 l 0) "http://www.classify.org/safesurf/" l gen true r (SS~~000 1))' />
<meta name="DC.Type" content="reference" />
<meta name="DC.Title" content="PCML struct tag" />
<meta name="abstract" content="The PCML struct tag can be expanded with the following elements." />
<meta name="description" content="The PCML struct tag can be expanded with the following elements." />
<meta name="DC.Relation" scheme="URI" content="pcmlsyn.htm" />
<meta name="copyright" content="(C) Copyright IBM Corporation 2006" />
<meta name="DC.Rights.Owner" content="(C) Copyright IBM Corporation 2006" />
<meta name="DC.Format" content="XHTML" />
<meta name="DC.Identifier" content="pcmlsttg" />
<meta name="DC.Language" content="en-us" />
<!-- All rights reserved. Licensed Materials Property of IBM -->
<!-- US Government Users Restricted Rights -->
<!-- Use, duplication or disclosure restricted by -->
<!-- GSA ADP Schedule Contract with IBM Corp. -->
<link rel="stylesheet" type="text/css" href="./ibmdita.css" />
<link rel="stylesheet" type="text/css" href="./ic.css" />
<title>PCML struct tag</title>
</head>
<body id="pcmlsttg"><a name="pcmlsttg"><!-- --></a>
<!-- Java sync-link --><script language="Javascript" src="../rzahg/synch.js" type="text/javascript"></script>
<h1 class="topictitle1">PCML struct tag</h1>
<div><p>The PCML struct tag can be expanded with the following elements.</p>
<div class="section"><pre><strong>&lt;struct name=</strong><em>"name"</em>
<strong>[ count=</strong><em>"{number | data-name }"</em><strong>]</strong>
<strong>[ maxvrm=</strong><em>"version-string"</em><strong> ]</strong>
<strong>[ minvrm=</strong><em>"version-string"</em><strong> ]</strong>
<strong>[ offset=</strong><em>"{number | data-name }"</em><strong> ]</strong>
<strong>[ offsetfrom=</strong><em>"{number | data-name | struct-name }"</em><strong> ]</strong>
<strong>[ outputsize=</strong><em>"{number | data-name }"</em><strong> ]</strong>
<strong>[ usage=</strong><em>"{ inherit | input | output | inputoutput }"</em><strong> ]</strong><strong>&gt;</strong>
<strong>&lt;/struct&gt;</strong></pre>
<p>The following table lists the struct tag
attributes. Each entry includes the attribute name, the possible valid values,
and a description of the attribute.</p>
<div class="tablenoborder"><table cellpadding="4" cellspacing="0" summary="" width="100%" frame="border" border="1" rules="all"><thead align="left"><tr class="tablemainheaderbar"><th valign="top" width="33.44481605351171%" id="d0e81">Attribute</th>
<th valign="top" width="33.44481605351171%" id="d0e83">Value</th>
<th valign="top" width="33.11036789297659%" id="d0e85">Description</th>
</tr>
</thead>
<tbody><tr><td valign="top" width="33.44481605351171%" headers="d0e81 "><strong>name=</strong></td>
<td valign="top" width="33.44481605351171%" headers="d0e83 "><em>name</em></td>
<td valign="top" width="33.11036789297659%" headers="d0e85 ">Specifies the name of the <strong>&lt;struct&gt; element</strong></td>
</tr>
<tr><td valign="top" width="33.44481605351171%" headers="d0e81 "><strong>count=</strong></td>
<td valign="top" width="33.44481605351171%" headers="d0e83 "><em>number</em> where <em>number</em> defines a fixed, never-changing sized
array. <p><em>data-name</em> where <em>data-name</em> defines the name of a <strong> &lt;data&gt;</strong>
element within the PCML document that will contain, at runtime, the number
of elements in the array. The <em> data-name</em> 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 <strong>&lt;data&gt;</strong> element that is defined
with <strong>type=</strong><em>"int"</em>. See <a href="lengthprecisionrelative.htm#lengthprecisionrelative__resolvingrelativenames">Resolving
Relative Names</a> for more information on how relative names are resolved.</p>
</td>
<td valign="top" width="33.11036789297659%" headers="d0e85 ">Specifies that the element is an array and identifies the number of
entries in the array. <p>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.</p>
</td>
</tr>
<tr><td valign="top" width="33.44481605351171%" headers="d0e81 "><strong>maxvrm=</strong></td>
<td valign="top" width="33.44481605351171%" headers="d0e83 "><em>version-string</em></td>
<td valign="top" width="33.11036789297659%" headers="d0e85 ">Specifies the highest version of i5/OS™ on which the element exists. If the
version of i5/OS 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 <strong>maxvrm</strong> element
is helpful for defining program interfaces which differ between releases of i5/OS.
<p>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.</p>
</td>
</tr>
<tr><td valign="top" width="33.44481605351171%" headers="d0e81 "><strong>minvrm=</strong></td>
<td valign="top" width="33.44481605351171%" headers="d0e83 "><em>version-string</em></td>
<td valign="top" width="33.11036789297659%" headers="d0e85 ">Specifies the lowest version of i5/OS on which this element exists. If
the version of i5/OS 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 i5/OS.
<p>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.</p>
</td>
</tr>
<tr><td valign="top" width="33.44481605351171%" headers="d0e81 "><strong>offset=</strong></td>
<td valign="top" width="33.44481605351171%" headers="d0e83 "><em>number</em> where <em>number</em> defines a fixed, never-changing offset.
<p><em>data-name</em> where <em>data-name</em> defines the name of a <strong> &lt;data&gt;</strong>
element within the PCML document that will contain, at runtime, the offset
to the element. The <strong> data-name</strong> 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 <strong>&lt;data&gt;</strong> element that is defined with <strong>type=</strong><em>"int"</em>.
See <a href="lengthprecisionrelative.htm#lengthprecisionrelative__resolvingrelativenames">Resolving
Relative Names</a> for more information on how relative names are resolved.</p>
</td>
<td valign="top" width="33.11036789297659%" headers="d0e85 ">Specifies the offset to the <strong>&lt;struct&gt;</strong> element within an output
parameter. <p>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 <strong>offset</strong> attribute is used to describe the
offset to this <strong>&lt;struct&gt;</strong> element.</p>
<p><strong>Offset</strong> is used in
conjunction with the <strong>offsetfrom</strong> attribute. If the <strong>offsetfrom</strong> attribute
is not specified, the base location for the offset specified on the <strong>offset</strong> attribute
is the parent of the element. See <a href="#pcmlsttg__pcmlsttgspecifyingoffsets">Specifying
Offsets</a> for more information on how to use the <strong>offset</strong> and <strong>offsetfrom</strong> attributes.</p>
<p>The <strong>offset</strong> and <strong>offsetfrom</strong> attributes are only used to process output data from a program. These attributes
do not control the offset or displacement of input data.</p>
<p>If the attribute
is omitted, the location of the data for the element is immediately following
the preceding element in the parameter, if any.</p>
</td>
</tr>
<tr><td valign="top" width="33.44481605351171%" headers="d0e81 "><strong>offsetfrom=</strong></td>
<td valign="top" width="33.44481605351171%" headers="d0e83 "><em>number</em> where <em>number</em> defines a fixed, never-changing base
location. A <em>number</em> attribute is most typically used to specify <strong>number=</strong><em>"0"</em> indicating
that the offset is an absolute offset from the beginning of the parameter.
<p><em>data-name</em> where <em>data-name</em> defines the name of a <strong> &lt;data&gt;</strong>
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 <strong> offset</strong> attribute
will be relative to the location of the element specified on this attribute.
The <em>data-name</em> 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 <a href="lengthprecisionrelative.htm#lengthprecisionrelative__resolvingrelativenames"> Resolving
Relative Names</a> for more information on how relative names are resolved.</p>
<p><em>struct-name</em> where <em>struct-name</em> defines
the name of a <strong> &lt;struct&gt;</strong> 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 <strong> offset</strong> attribute will be relative
to the location of the element specified on this attribute. The <em>struct-name</em> 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 <a href="lengthprecisionrelative.htm#lengthprecisionrelative__resolvingrelativenames"> Resolving
Relative Names</a> for more information on how relative names are resolved.</p>
</td>
<td valign="top" width="33.11036789297659%" headers="d0e85 ">Specifies the base location from which the <strong>offset</strong> attribute
is relative. <p>If the <strong>offsetfrom</strong> attribute is not specified, the
base location for the offset specified on the <strong>offset</strong> attribute is the
parent of this element. See <a href="#pcmlsttg__pcmlsttgspecifyingoffsets">Specifying
Offsets</a> for more information on how to use the <strong>offset</strong> and <strong>offsetfrom</strong> attributes.</p>
<p>The <strong>offset</strong> and <strong>offsetfrom</strong> attributes are only used to process output data from a program. These attributes
do not control the offset or displacement of input data.</p>
</td>
</tr>
<tr><td valign="top" width="33.44481605351171%" headers="d0e81 "><strong>outputsize=</strong></td>
<td valign="top" width="33.44481605351171%" headers="d0e83 "><em>number</em> where <em>number</em> defines a fixed,never-changing number
of bytes to reserve. <p><em>data-name</em> where <em>data-name</em> defines the
name of a <strong> &lt;data&gt;</strong> element within the PCML document that will contain,
at runtime, the number of bytes to reserve for output data. The <em>data-name</em> 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 <strong>&lt;data&gt;</strong> element
that is defined with <strong>type=</strong><em>"int"</em>. See <a href="lengthprecisionrelative.htm#lengthprecisionrelative__resolvingrelativenames">Resolving
Relative Names</a> for more information on how relative names are resolved.</p>
</td>
<td valign="top" width="33.11036789297659%" headers="d0e85 ">Specifies the number of bytes to reserve for output data for the element.
For output parameters which are variable in length, the <strong>outputsize</strong> attribute
is needed to specify how many bytes must be reserved for data to be returned
from the server program. <strong>Outputsize</strong> 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. <p><strong>Outputsize</strong> is
not necessary and must not be specified for fixed-size output parameters.</p>
<p>The
value specified on the attribute is used as the total size for the element
including all children of the element. Therefore, the <strong>outputsize</strong> attribute
is ignored on any children or descendants of the element.</p>
<p>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 <strong>&lt;struct&gt;</strong> element.</p>
</td>
</tr>
<tr><td rowspan="4" valign="top" width="33.44481605351171%" headers="d0e81 "><strong>usage=</strong></td>
<td valign="top" width="33.44481605351171%" headers="d0e83 "><em>inherit</em></td>
<td valign="top" width="33.11036789297659%" headers="d0e85 ">Usage is inherited from the parent element. If the structure does not
have a parent, usage is assumed to be <strong>inputoutput</strong>.</td>
</tr>
<tr><td valign="top" width="33.44481605351171%" headers="d0e83 "><em>input</em></td>
<td valign="top" width="33.11036789297659%" headers="d0e85 ">The structure is an input value to the host program. For character
and numeric types, the appropriate conversion is performed.</td>
</tr>
<tr><td valign="top" width="33.44481605351171%" headers="d0e83 "><em>output</em></td>
<td valign="top" width="33.11036789297659%" headers="d0e85 ">The structure is an output value from the host program. For character
and numeric types, the appropriate conversion is performed.</td>
</tr>
<tr><td valign="top" width="33.44481605351171%" headers="d0e83 "><em>inputoutput</em></td>
<td valign="top" width="33.11036789297659%" headers="d0e85 ">The structure is both and input and an output value.</td>
</tr>
</tbody>
</table>
</div>
</div>
<div class="section" id="pcmlsttg__pcmlsttgspecifyingoffsets"><a name="pcmlsttg__pcmlsttgspecifyingoffsets"><!-- --></a><h4 class="sectiontitle">Specifying offsets</h4><p>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.</p>
<p>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.</p>
<p>For offsets, since the distance is from the beginning
of the parameter, specify <strong>offsetfrom="0"</strong>. The following is an example
of an offset from the beginning of the parameter:</p>
<pre>&lt;pcml version="1.0"&gt;
&lt;program name="myprog" path="/QSYS.lib/MYLIB.lib/MYPROG.pgm"&gt;
&lt;!-- receiver variable contains a path --&gt;
&lt;struct name="receiver" usage="output" outputsize="2048"&gt;
&lt;data name="pathType" type="int" length="4" /&gt;
&lt;data name="offsetToPathName" type="int" length="4" /&gt;
&lt;data name="lengthOfPathName" type="int" length="4" /&gt;
&lt;data name="pathName" type="char" length="lengthOfPathName"
<strong>offset="offsetToPathName" offsetfrom="0"</strong>/&gt;
&lt;/struct&gt;
&lt;/program&gt;
&lt;/pcml&gt;</pre>
<p>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:</p>
<pre>&lt;pcml ="1.0"&gt;
&lt;program name="myprog" path="/QSYS.lib/MYLIB.lib/MYPROG.pgm"&gt;
&lt;!-- receiver variable contains an object --&gt;
&lt;struct name="receiver" usage="output" &gt;
&lt;data name="objectName" type="char" length="10" /&gt;
&lt;data name="libraryName" type="char" length="10" /&gt;
&lt;data name="objectType" type="char" length="10" /&gt;
&lt;struct name="pathInfo" usage="output" outputsize="2048" &gt;
&lt;data name="pathType" type="int" length="4" /&gt;
&lt;data name="offsetToPathName" type="int" length="4" /&gt;
&lt;data name="lengthOfPathName" type="int" length="4" /&gt;
&lt;data name="pathName" type="char" length="lengthOfPathName"
<strong>offset="offsetToPathName" offsetfrom="pathInfo"</strong>/&gt;
&lt;/struct&gt;
&lt;/struct&gt;
&lt;/program&gt;
&lt;/pcml&gt;</pre>
</div>
</div>
<div>
<div class="familylinks">
<div class="parentlink"><strong>Parent topic:</strong> <a href="pcmlsyn.htm" title="PCML consists of the following tags, each of which has its own attribute tags.">PCML syntax</a></div>
</div>
</div>
</body>
</html>
Reference in New Issue Copy Permalink