ibm-information-center/dist/eclipse/plugins/i5OS.ic.apis_5.4.0.1/qszlstra.htm

535 lines
18 KiB
HTML
Raw Normal View History

2024-04-02 14:02:31 +00:00
<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8">
<meta name="Copyright" content="Copyright (c) 2006 by IBM Corporation">
<title>List Registered Application Information (QSZLSTRA, QszListRegAppInfo)
API</title>
<!-- Begin Header Records -->
<!-- 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. -->
<!-- Created for V5R1 -->
<!-- Change History: -->
<!-- YYMMDD USERID Change description -->
<!-- Edited by Kersten Jan 02 -->
<!-- Edited by James Masanz July 03 -->
<!-- End Header Records -->
<link rel="stylesheet" type="text/css" href="../rzahg/ic.css">
</head>
<body>
<a name="Top_Of_Page"></a>
<!--Java sync-link-->
<script type="text/javascript" language="Javascript" src="../rzahg/synch.js">
</script>
<h2>List Registered Application Information (QSZLSTRA, QszListRegAppInfo)
API</h2>
<div class="box" style="width: 80%;">
<br>
&nbsp;&nbsp;Required Parameter Group:<br>
<!-- iddvc RMBR -->
<br>
<table width="100%">
<tr>
<td align="center" valign="top" width="10%">1</td>
<td align="left" valign="top" width="50%">Application information path name for
input</td>
<td align="left" valign="top" width="20%">Input</td>
<td align="left" valign="top" width="20%">Char(*)</td>
</tr>
<tr>
<td align="center" valign="top">2</td>
<td align="left" valign="top">Application information path name for output</td>
<td align="left" valign="top">Output</td>
<td align="left" valign="top">Char(*)</td>
</tr>
<tr>
<td align="center" valign="top">3</td>
<td align="left" valign="top">Continuation handle input</td>
<td align="left" valign="top">Input</td>
<td align="left" valign="top">Binary(4)</td>
</tr>
<tr>
<td align="center" valign="top">4</td>
<td align="left" valign="top">Continuation handle output</td>
<td align="left" valign="top">Output</td>
<td align="left" valign="top">Binary(4)</td>
</tr>
<tr>
<td align="center" valign="top">5</td>
<td align="left" valign="top">Error code</td>
<td align="left" valign="top">I/O</td>
<td align="left" valign="top">Char(*)</td>
</tr>
</table>
<br>
&nbsp;&nbsp;Service Program Name: QSZRAIRA<br>
<!-- iddvc RMBR -->
<br>
&nbsp;&nbsp;Default Public Authority: *EXCLUDE<br>
<!-- iddvc RMBR -->
<br>
&nbsp;&nbsp;Threadsafe: No<br>
<!-- iddvc RMBR -->
<br>
</div>
<p>The List Registered Application Information (QSZLSTRA, QszListRegAppInfo)
API retrieves the results of a query of the i5/OS Registered Application
Information Repository. Data is returned as an XML document.</p>
<br>
<h3>Authorities and Locks</h3>
<dl>
<dt><em>Library authority (INPUT and OUTPUT)</em></dt>
<dd>*EXECUTE<br>
<br>
</dd>
<dt><em>Authority for user space containing XML input document</em></dt>
<dd>*USE<br>
<br>
</dd>
<dt><em>Authority for user space containing XML output document</em></dt>
<dd>*CHANGE<br>
<br>
</dd>
<dt><em>User space lock (INPUT)</em></dt>
<dd>*EXCLRD<br>
<br>
</dd>
<dt><em>User space lock (OUTPUT)</em></dt>
<dd>*EXCL<br>
<br>
</dd>
<dt><em>Stream file directory authority (INPUT)</em></dt>
<dd>*RX<br>
<br>
</dd>
<dt><em>Stream file directory authority (OUTPUT)</em></dt>
<dd>*RWX<br>
<br>
</dd>
<dt><em>Authority for stream file containing XML input document</em></dt>
<dd>*R<br>
<br>
</dd>
<dt><em>Authority for stream file containing XML output document</em></dt>
<dd>*RW</dd>
</dl>
<br>
<h3>Required Parameter Group</h3>
<dl>
<dt><strong>Application information path name input</strong></dt>
<dd>INPUT; CHAR(*)
<p>The path name of the object that contains the XML document with the
information of the components to be listed by the API. This may be a path to a
user space (*USRSPC) or a path to a stream file (*STMF). The path name should be
specified in the Qlg_Path_Name_T format. If a pointer is specified in the path
name format, it must be 16-byte aligned. If not, unpredictable results may
occur. For more information on this structure, see <a href="../apiref/pns.htm">Path name
format</a>. The information contained in this object must be given to the API
as an XML document according to the data type definition (DTD). For a detailed
description of the DTD, see <a href="softwarecompdtd.htm">Software Components
DTD</a>. For a detailed description of the information that should be contained
in this object, see <a href="#HDRSZLSTAP">XML document when listing component
information</a>.</p>
</dd>
<dt><strong>Application information path name output</strong></dt>
<dd>OUTPUT; CHAR(*)
<p>The path name of the object that contains the XML document listing the
results of the query. This may be a path to a user space (*USRSPC) or a path to
a stream file (*STMF). The path name should be specified in the Qlg_Path_Name_T
format. If a pointer is specified in the path name format, it must be 16-byte
aligned. If not, unpredictable results may occur. For more information on this
structure, see <a href="../apiref/pns.htm">Path name format</a>. The information
contained in this object is returned to the API caller as an XML document
according to the data type definition (DTD).</p>
</dd>
<dt><strong>Continuation handle input</strong></dt>
<dd>INPUT; BINARY(4)
<p>This is a special value that should be used to request the remaining entries
of a previous query when a user space was provided to return the component
information, but the size of the space was not enough to hold the information.
This value should be taken from the Continuation Handle Output parameter
returned in the previous call. This parameter must be set to 0 on the first
call to this API. When you specify a continuation handle for this parameter,
all other parameters must have the same values as the call to the API that
generated the continuation handle. Failure to do so may result in incomplete or
inaccurate information.</p>
</dd>
<dt><strong>Continuation handle output</strong></dt>
<dd>OUTPUT; BINARY(4)
<p>This value indicates whether the list returned is complete or if the space
provided to hold the information being returned was not enough. If this value
is 0, then the list is complete. If the value is different than 0, it means
that only part of the information was returned, so a second call is needed to
return the remaining information. Only complete components will be returned. If
a component cannot fit in the space provided, the component will not be
returned; that is, a complete XML document will be returned with as many
&lt;Component&gt; tags as can fit in the space provided.</p>
</dd>
<dt><strong>Error code</strong></dt>
<dd>I/O; CHAR(*)
<p>The structure in which to return error information. For the format of the
structure, see <a href="../apiref/error.htm#hdrerrcod">Error Code Parameter</a>.</p>
</dd>
</dl>
<br>
<h3><a name="HDRSZLSTAP">XML Document when listing component
information</a></h3>
<p>This object may be a stream file (*STMF) or a user space (*USRSPC) object.
In either case, the contents of the object must be an XML document that
conforms to the specified rules.</p>
<p>All elements and attributes defined in the data type definition (DTD) are
allowed. See below for <a href="#HDRSZLSTRULZ">examples of possible
queries</a>. See <a href="softwarecompdtd.htm">Software Components DTD</a> for
a detailed description of each element and attribute.</p>
<p>In addition, special characters can be used to increase query
capabilities.</p>
<p>The percent sign (%) stands for an unknown string of 0 or more characters.
Available options are:</p>
<table cellpadding="5">
<!-- cols="10 90" -->
<tr>
<td align="left" valign="top"><em>%xxx</em></td>
<td align="left" valign="top">The <strong>ends with</strong> selection
criteria, where xxx are the characters with which you want the attribute value to
end.</td>
</tr>
<tr>
<td align="left" valign="top"><em>xxx%</em></td>
<td align="left" valign="top">The <strong>starts with</strong> selection
criteria, where xxx are the characters with which you want the attribute value to
start.</td>
</tr>
<tr>
<td align="left" valign="top"><em>%xxx%</em></td>
<td align="left" valign="top">The <strong>contains</strong> selection criteria,
where xxx are the characters you want to be contained in your attribute value.</td>
</tr>
</table>
<p>An underline character (_) stands for any single character.</p>
<p>If you do not specify any of these characters, it indicates that you want an
exact match.</p>
<p><a name="HDRSZLSTRULZ">The rules to follow in your XML document to do the
query are:</a></p>
<ol>
<li>When product, version, component name, instance, feature or vendor are not
present or are empty, it indicates that you want any match on those attributes.
For example, if you do not specify ComponentVersion, ComponentName, Instance and ComponentVendor
attributes or if they are empty, then all applications that match the specified ProductName
will be returned. In the example below, all entries matching a
5722SS1 product will be returned (no extended data will be returned since the
ExtendedData element is not present). The ComponentName attribute was
specified as empty since it is required by the DTD.
<pre>
&lt;?xml version=&quot;1.0&quot; encoding=&quot;UTF-8&quot;?&gt;
&lt;!DOCTYPE RegAppInfoRepository SYSTEM &quot;/QIBM/XML/DTD/QszRegAppInfoRepository.dtd&quot;&gt;
&lt;RegAppInfoRepository DTDVersion=&quot;1.0&quot;&gt;
&lt;Component ProductName=&quot;5722SS1&quot; ComponentName=&quot;&quot; PackagedProduct=&quot;_&quot;&gt; &lt;/Component&gt;
&lt;/RegAppInfoRepository&gt;
</pre>
</li>
<li>When you specify the PackagedProduct attribute with a value of 1, it
indicates that you want only information about i5/OS packaged products. For
example, if you specify the starts with selection criteria as shown in the
following XML document, then all i5/OS packaged product components with a
ComponentName starting with 5 will be returned. Note that the ProductName attribute
was defined because it is required by the DTD.
<pre>
&lt;?xml version=&quot;1.0&quot; encoding=&quot;UTF-8&quot;?&gt;
&lt;!DOCTYPE RegAppInfoRepository SYSTEM &quot;/QIBM/XML/DTD/QszRegAppInfoRepository.dtd&quot;&gt;
&lt;RegAppInfoRepository DTDVersion=&quot;1.0&quot;&gt;
&lt;Component ProductName=&quot;&quot; ComponentName=&quot;5%&quot; PackagedProduct=&quot;1&quot;&gt;
&lt;/Component&gt;
&lt;/RegAppInfoRepository&gt;
</pre>
</li>
<li>When you specify one of the allowed attributes or elements contained in the
&lt;ExtendedData&gt; element and one of the attributes or elements is empty, it
indicates that you want that data retrieved. For example, if you want to know
the InstallerType for a component, you can specify the ExtendedData element as
follows:
<pre>
&lt;?xml version=&quot;1.0&quot; encoding=&quot;UTF-8&quot;?&gt;
&lt;!DOCTYPE RegAppInfoRepository SYSTEM &quot;/QIBM/XML/DTD/QszRegAppInfoRepository.dtd&quot;&gt;
&lt;RegAppInfoRepository DTDVersion=&quot;1.0&quot;&gt;
&lt;Component ProductName=&quot;5722TC1&quot; ComponentVersion=&quot;V5R3M0&quot;
ComponentName=&quot;5050&quot; FeatureName=&quot;0000&quot; PackagedProduct=&quot;1&quot;&gt;
&lt;ExtendedData InstallerType=&quot;&quot;&gt;
&lt;/ExtendedData&gt;
&lt;/Component&gt;
&lt;/RegAppInfoRepository&gt;
</pre>
</li>
<li>When you specify one of the allowed attributes or elements contained in the
&lt;ExtendedData&gt; element and it contains a value, it indicates that you
want returned the component or components that have the attribute or element specified (depending on the selection criteria). For
example, if you want to know all the components that were installed by ISJE:
<pre>
&lt;?xml version=&quot;1.0&quot; encoding=&quot;UTF-8&quot;?&gt;
&lt;!DOCTYPE RegAppInfoRepository SYSTEM &quot;/QIBM/XML/DTD/QszRegAppInfoRepository.dtd&quot;&gt;
&lt;RegAppInfoRepository DTDVersion=&quot;1.0&quot;&gt;
&lt;Component ProductName=&quot;&quot; ComponentName=&quot;&quot;&gt;
&lt;ExtendedData InstallerType=&quot;ISJE&quot;&gt; &lt;/ExtendedData&gt;
&lt;/Component&gt;
&lt;/RegAppInfoRepository&gt;
</pre>
</li>
<li>When you specify the ExtendedData element with no attributes or elements
inside, it indicates that you want returned all available information for that
component.
<pre>
&lt;?xml version=&quot;1.0&quot; encoding=&quot;UTF-8&quot;?&gt;
&lt;!DOCTYPE RegAppInfoRepository SYSTEM &quot;/QIBM/XML/DTD/QszRegAppInfoRepository.dtd&quot;&gt;
&lt;RegAppInfoRepository DTDVersion=&quot;1.0&quot;&gt;
&lt;Component ProductName=&quot;5722TC1&quot; ComponentVersion=&quot;V5R3M0&quot;
ComponentName=&quot;5050&quot; FeatureName=&quot;0000&quot;
PackagedProduct=&quot;1&quot;&gt;
&lt;ExtendedData/&gt;
&lt;/Component&gt;
&lt;/RegAppInfoRepository&gt;
</pre>
</li>
</ol>
<p>Additional examples illustrating the way to define an XML document for input to
this API follow:</p>
<br>
<h3>List all information for all i5/OS packaged products</h3>
<pre>
&lt;?xml version=&quot;1.0&quot; encoding=&quot;UTF-8&quot;?&gt;
&lt;!DOCTYPE RegAppInfoRepository SYSTEM &quot;/QIBM/XML/DTD/QszRegAppInfoRepository.dtd&quot;&gt;
&lt;RegAppInfoRepository DTDVersion=&quot;1.0&quot;&gt;
&lt;Component ProductName=&quot;&quot; ComponentName=&quot;&quot; PackagedProduct=&quot;1&quot;&gt;
&lt;ExtendedData&gt;
&lt;/ExtendedData&gt;
&lt;/Component&gt;
&lt;/RegAppInfoRepository&gt;
</pre>
<br>
<h3>List all i5/OS packaged products with a product name ending in &quot;TC1&quot;.</h3>
<pre>
&lt;?xml version=&quot;1.0&quot; encoding=&quot;UTF-8&quot;?&gt;
&lt;!DOCTYPE RegAppInfoRepository SYSTEM &quot;/QIBM/XML/DTD/QszRegAppInfoRepository.dtd&quot;&gt;
&lt;RegAppInfoRepository DTDVersion=&quot;1.0&quot;&gt;
&lt;Component ProductName=&quot;%TC1&quot; ComponentName=&quot;&quot; PackagedProduct=&quot;1&quot;/&gt;
&lt;/RegAppInfoRepository&gt;
</pre>
<br>
<h3>List all i5/OS packaged products with &quot;57&quot; as the first
two characters of the product name and
&quot;TC1&quot; as the last three characters.</h3>
<pre>
&lt;?xml version=&quot;1.0&quot; encoding=&quot;UTF-8&quot;?&gt;
&lt;!DOCTYPE RegAppInfoRepository SYSTEM &quot;/QIBM/XML/DTD/QszRegAppInfoRepository.dtd&quot;&gt;
&lt;RegAppInfoRepository DTDVersion=&quot;1.0&quot;&gt;
&lt;Component ProductName=&quot;57__TC1&quot; ComponentName=&quot;&quot; PackagedProduct=&quot;1&quot;/&gt;
&lt;/RegAppInfoRepository&gt;
</pre>
<p>Notice in this example the use of the underline character. In this case we
know the product name for i5/OS packaged products is 7 characters long.
The underline character should not be used if you do not know the number of
characters in between.</p>
<br>
<h3>List all available information for components containing
the string &quot;tool&quot; in
the component name.</h3>
<pre>
&lt;?xml version=&quot;1.0&quot; encoding=&quot;UTF-8&quot;?&gt;
&lt;!DOCTYPE RegAppInfoRepository SYSTEM &quot;/QIBM/XML/DTD/QszRegAppInfoRepository.dtd&quot;&gt;
&lt;RegAppInfoRepository DTDVersion=&quot;1.0&quot;&gt;
&lt;Component ProductName=&quot;&quot; ComponentName=&quot;%tool%&quot;&gt;
&lt;ExtendedData&gt;&lt;/ExtendedData&gt;
&lt;/Component&gt;
&lt;/RegAppInfoRepository&gt;
</pre>
<br>
<h3>List all supported i5/OS packaged products.</h3>
<p>Having the following XML document, we can get the list of all supported
i5/OS packaged products.</p>
<pre>
&lt;?xml version=&quot;1.0&quot; encoding=&quot;UTF-8&quot;?&gt;
&lt;!DOCTYPE RegAppInfoRepository SYSTEM &quot;/QIBM/XML/DTD/QszRegAppInfoRepository.dtd&quot;&gt;
&lt;RegAppInfoRepository DTDVersion=&quot;1.0&quot;&gt;
&lt;Component ProductName=&quot;&quot; ComponentName=&quot;&quot; PackagedProduct=&quot;1&quot;&gt;
&lt;ExtendedData Supported=&quot;1&quot;&gt;
&lt;/ExtendedData&gt;
&lt;/Component&gt;
&lt;/RegAppInfoRepository&gt;
</pre>
<br>
<h3>Error Messages</h3>
<table width="100%" cellpadding="5">
<!-- cols="15 85" -->
<tr>
<th align="left" valign="top">Message ID</th>
<th align="left" valign="top">Error Message Text</th>
</tr>
<tr>
<td width="15%" valign="top">CPF24B4 E</td>
<td width="85%" valign="top">Severe error addressing parameter list.</td>
</tr>
<tr>
<td align="left" valign="top">CPF3CF1 E</td>
<td align="left" valign="top">Error code parameter not valid.</td>
</tr>
<tr>
<td align="left" valign="top">CPF3CF2 E</td>
<td align="left" valign="top">Error(s) occurred during running of &amp;1 API.</td>
</tr>
<tr>
<td align="left" valign="top">CPF9872 E</td>
<td align="left" valign="top">Program or service program &amp;1 in library &amp;2
ended.</td>
</tr>
<tr>
<td align="left" valign="top">CPF3C1E E</td>
<td align="left" valign="top">Required parameter &amp;1 omitted.</td>
</tr>
<tr>
<td align="left" valign="top">CPF0CC1 E</td>
<td align="left" valign="top">Error initializing the XML parser.</td>
</tr>
<tr>
<td align="left" valign="top">CPF0CC2 E</td>
<td align="left" valign="top">Error found on XML input document.</td>
</tr>
<tr>
<td align="left" valign="top">CPF0CC7 E</td>
<td align="left" valign="top">Requested function not successful.</td>
</tr>
<tr>
<td align="left" valign="top">CPF0CD2 E</td>
<td align="left" valign="top">Application information path name not valid.</td>
</tr>
<tr>
<td align="left" valign="top">CPF0CDF E</td>
<td align="left" valign="top">Continuation handle not valid.</td>
</tr>
</table>
<br>
<hr>
API introduced: V5R1
<hr>
<table cellpadding="2" cellspacing="2" align="center">
<tr align="center">
<td valign="middle" align="center"><a href="#Top_Of_Page">Top</a> | <a href=
"sw1.htm">Software Product APIs</a> | <a href="aplist.htm">APIs by
category</a></td>
</tr>
</table>
</body>
</html>