friedkiwi/ibm-information-center
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity
0332907f0f
ibm-information-center/dist/eclipse/plugins/i5OS.ic.apis_5.4.0.1/qrzsche.htm

830 lines
23 KiB
HTML
Raw Normal View History

Add readme and dist folders
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>Search Hardware Resource Entry (QRZSCHE) 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. -->
<!-- GSA ADP Schedule Contract with IBM Corp. -->
<!-- Change History: -->
<!-- YYMMDD USERID Change description -->
<!-- This file has undergone html cleanup on 1/14/02 by JET -->
<!-- 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>Search Hardware Resource Entry (QRZSCHE) 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="40%">Resource name</td>
<td align="left" valign="top" width="25%">Output</td>
<td align="left" valign="top" width="25%">Char(32)</td>
</tr>
<tr>
<td align="center" valign="top">2</td>
<td align="left" valign="top">Resource criteria</td>
<td align="left" valign="top">Input</td>
<td align="left" valign="top">Char(*)</td>
</tr>
<tr>
<td align="center" valign="top">2</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;Default Public Authority: *EXCLUDE<br>
<!-- iddvc RMBR -->
<br>
&nbsp;&nbsp;Threadsafe: No<br>
<!-- iddvc RMBR -->
<br>
</div>
<p>The Search Hardware Resource Entry (QRZSCHE) API retrieves the resource name
of a hardware resource that matches the request criteria. The user of the API
supplies the request criteria with key values. The first or next resource name
that matches the request criteria is returned. Each call of this API returns
only one resource name. Multiple calls may be necessary to obtain all resource
names from a possible list of resource names. Each resource name can be used
with other hardware resource APIs to get more information about the specific
hardware resource.</p>
<p><strong>Note:</strong> Some key values are used as a singular search
criterion rather than as part of a more complex search. Searches that use
singular search criterion have very concise results; for example, a search for
<em>console controller</em> can return a maximum of one possible resource
name.</p>
<p>Some key values can be used in conjunction with other key values to make a
search more precise.</p>
<p>You can use this API to do the following:</p>
<ul>
<li>Search for a hardware resource by type number</li>
<li>Search for a hardware resource by model number</li>
<li>Search for a hardware resource by serial number</li>
<li>Search for all hardware resources. No special order or hierarchy is used
when the resource names are returned.</li>
<li>Search for the system data</li>
<li>Search for a hardware resource by bus number</li>
<li>Search for a controller storage resource</li>
<li>Search for a controller workstation resource</li>
<li>Search for a controller communications resource</li>
<li>Search for an IOP storage resource</li>
<li>Search for an IOP workstation resource</li>
<li>Search for an IOP communications resource</li>
<li>Search for the control panel</li>
<li>Search for the service processor</li>
<li>Search for the bus controller</li>
<li>Search for the memory cards</li>
<li>Search for the console controller</li>
<li>Search for the console device</li>
<li>Search for the main processor</li>
<li>Search for system hardware</li>
<li>Search for an input/output processor (IOP) shared object clustering (SOC)
resource</li>
<li>Search for the electronic-customer-support communications resource.</li>
<li>Search for an IOP cryptographic resource</li>
<li>Search for a cryptographic adapter</li>
<li>Search for a cryptographic device</li>
<li>Search for the processor capacity card</li>
<li>Search for the interactive card</li>
</ul>
<p><strong>Note:</strong> Some of the search criteria can be used only by
themselves.</p>
<br>
<h3>Authorities and Locks</h3>
<dl>
<dt><em>API Public Authority</em></dt>
<dd>*EXCLUDE</dd>
</dl>
<br>
<h3>Required Parameter Group</h3>
<dl>
<dt><strong>Resource name</strong></dt>
<dd>OUTPUT; CHAR(32)
<p>The receiver variable that receives the resource name based on the request
criteria. The resource name is a 32-character field that is left-justified and
padded with trailing blanks.</p>
</dd>
<dt><strong>Resource criteria</strong></dt>
<dd>INPUT; CHAR(*)
<p>The criteria for which the search is processed. See <a href="#HDRSCHECRT">
Format of the Resource Criteria</a> for details about this format.</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="HDRSCHECRT">Format of the Resource Criteria</a></h3>
<table border width="80%">
<tr>
<th align="center" valign="bottom" colspan="2">Offset</th>
<th align="left" valign="bottom" rowspan="2">Type</th>
<th align="left" valign="bottom" rowspan="2">Field</th>
</tr>
<tr>
<th align="center" valign="bottom">Dec</th>
<th align="center" valign="bottom">Hex</th>
</tr>
<tr>
<td align="center" valign="top" width="10%">0</td>
<td align="center" valign="top" width="10%">0</td>
<td align="left" valign="top" width="20%">BINARY(4)</td>
<td align="left" valign="top" width="60%">Length of structure</td>
</tr>
<tr>
<td align="center" valign="top">4</td>
<td align="center" valign="top">4</td>
<td align="left" valign="top">BINARY(4)</td>
<td align="left" valign="top">Offset to first variable length record</td>
</tr>
<tr>
<td align="center" valign="top">8</td>
<td align="center" valign="top">8</td>
<td align="left" valign="top">BINARY(4)</td>
<td align="left" valign="top">Number of variable length records</td>
</tr>
<tr>
<td align="center" valign="top">12</td>
<td align="center" valign="top">C</td>
<td align="left" valign="top">CHAR(16)</td>
<td align="left" valign="top">Handle</td>
</tr>
<tr>
<td align="center" valign="top">28</td>
<td align="center" valign="top">1C</td>
<td align="left" valign="top">BINARY(4)</td>
<td align="left" valign="top">Search resource</td>
</tr>
<tr>
<td align="center" valign="top">32</td>
<td align="center" valign="top">20</td>
<td align="left" valign="top">BINARY(4)</td>
<td align="left" valign="top">Search request</td>
</tr>
<tr>
<td align="center" valign="top">&nbsp;</td>
<td align="center" valign="top">&nbsp;</td>
<td align="left" valign="top">CHAR(*)</td>
<td align="left" valign="top">Variable length records</td>
</tr>
<tr>
<td align="left" valign="top" rowspan="4" colspan="2">These fields repeat for
each variable length record.</td>
<td align="left" valign="top">BINARY(4)</td>
<td align="left" valign="top">Size of variable length record</td>
</tr>
<tr>
<td align="left" valign="top">BINARY(4)</td>
<td align="left" valign="top">Key</td>
</tr>
<tr>
<td align="left" valign="top">BINARY(4)</td>
<td align="left" valign="top">Length of data</td>
</tr>
<tr>
<td align="left" valign="top">CHAR(*)</td>
<td align="left" valign="top">Data</td>
</tr>
</table>
<br>
<br>
<h3><a name="HDRSCHPFD1">Field Descriptions</a></h3>
<p><strong>Data.</strong> The following table identifies the data field and the
data type for the specified key.</p>
<table border width="80%">
<tr>
<th align="center" valign="bottom">Key</th>
<th align="left" valign="bottom">Field</th>
<th align="left" valign="bottom">Type</th>
</tr>
<tr>
<td align="center" valign="top" width="15%">-1</td>
<td align="left" valign="top" width="60%">All records<sup>1</sup></td>
<td align="left" valign="top" width="25%">CHAR(1)</td>
</tr>
<tr>
<td align="center" valign="top">1</td>
<td align="left" valign="top">Type (object type)<sup>2</sup></td>
<td align="left" valign="top">CHAR(10)</td>
</tr>
<tr>
<td align="center" valign="top">2</td>
<td align="left" valign="top">Model number<sup>2</sup></td>
<td align="left" valign="top">CHAR(10)</td>
</tr>
<tr>
<td align="center" valign="top">4</td>
<td align="left" valign="top">Serial number<sup>2</sup></td>
<td align="left" valign="top">CHAR(10)</td>
</tr>
<tr>
<td align="center" valign="top">6</td>
<td align="left" valign="top">System information<sup>1</sup></td>
<td align="left" valign="top">CHAR(1)</td>
</tr>
<tr>
<td align="center" valign="top">7</td>
<td align="left" valign="top">Bus number<sup>2</sup></td>
<td align="left" valign="top">BINARY(4)</td>
</tr>
<tr>
<td align="center" valign="top">8</td>
<td align="left" valign="top">Controller storage<sup>1</sup></td>
<td align="left" valign="top">CHAR(1)</td>
</tr>
<tr>
<td align="center" valign="top">9</td>
<td align="left" valign="top">Controller workstation<sup>1</sup></td>
<td align="left" valign="top">CHAR(1)</td>
</tr>
<tr>
<td align="center" valign="top">10</td>
<td align="left" valign="top">Controller communication<sup>1</sup></td>
<td align="left" valign="top">CHAR(1)</td>
</tr>
<tr>
<td align="center" valign="top">11</td>
<td align="left" valign="top">IOP storage<sup>1</sup></td>
<td align="left" valign="top">CHAR(1)</td>
</tr>
<tr>
<td align="center" valign="top">12</td>
<td align="left" valign="top">IOP workstation<sup>1</sup></td>
<td align="left" valign="top">CHAR(1)</td>
</tr>
<tr>
<td align="center" valign="top">13</td>
<td align="left" valign="top">IOP communication<sup>1</sup></td>
<td align="left" valign="top">CHAR(1)</td>
</tr>
<tr>
<td align="center" valign="top">14</td>
<td align="left" valign="top">Control panel<sup>1</sup></td>
<td align="left" valign="top">CHAR(1)</td>
</tr>
<tr>
<td align="center" valign="top">15</td>
<td align="left" valign="top">Service processor<sup>1</sup></td>
<td align="left" valign="top">CHAR(1)</td>
</tr>
<tr>
<td align="center" valign="top">16</td>
<td align="left" valign="top">Bus controller<sup>1</sup></td>
<td align="left" valign="top">CHAR(1)</td>
</tr>
<tr>
<td align="center" valign="top">17</td>
<td align="left" valign="top">Memory cards<sup>1</sup></td>
<td align="left" valign="top">CHAR(1)</td>
</tr>
<tr>
<td align="center" valign="top">18</td>
<td align="left" valign="top">Console controller<sup>1</sup></td>
<td align="left" valign="top">CHAR(1)</td>
</tr>
<tr>
<td align="center" valign="top">19</td>
<td align="left" valign="top">Console device<sup>1</sup></td>
<td align="left" valign="top">CHAR(1)</td>
</tr>
<tr>
<td align="center" valign="top">20</td>
<td align="left" valign="top">Main processor<sup>1</sup></td>
<td align="left" valign="top">CHAR(1)</td>
</tr>
<tr>
<td align="center" valign="top">21</td>
<td align="left" valign="top">System hardware<sup>1</sup></td>
<td align="left" valign="top">CHAR(1)</td>
</tr>
<tr>
<td align="center" valign="top">24</td>
<td align="left" valign="top">IOP SOC<sup>1</sup></td>
<td align="left" valign="top">CHAR(1)</td>
</tr>
<tr>
<td align="center" valign="top">25</td>
<td align="left" valign="top">Electronic-customer-support communications
resource<sup>3</sup></td>
<td align="left" valign="top">CHAR(1)</td>
</tr>
<tr>
<td align="center" valign="top">26</td>
<td align="left" valign="top">Primary-console-controller<sup>1</sup></td>
<td align="left" valign="top">CHAR(1)</td>
</tr>
<tr>
<td align="center" valign="top">27</td>
<td align="left" valign="top">Cryptographic IOP<sup>1</sup></td>
<td align="left" valign="top">CHAR(1)</td>
</tr>
<tr>
<td align="center" valign="top">28</td>
<td align="left" valign="top">Cryptographic IOA<sup>1</sup></td>
<td align="left" valign="top">CHAR(1)</td>
</tr>
<tr>
<td align="center" valign="top">29</td>
<td align="left" valign="top">Cryptographic device<sup>1</sup></td>
<td align="left" valign="top">CHAR(1)</td>
</tr>
<tr>
<td align="center" valign="top">30</td>
<td align="left" valign="top">Processor capacity card<sup>1</sup></td>
<td align="left" valign="top">CHAR(1)</td>
</tr>
<tr>
<td align="center" valign="top">31</td>
<td align="left" valign="top">Interactive card<sup>1</sup></td>
<td align="left" valign="top">CHAR(1)</td>
</tr>
<tr>
<td align="left" valign="top" colspan="3"><strong>Notes:</strong>
<table cellpadding="5">
<tr>
<td align="left" valign="top"><sup>1</sup></td>
<td align="left" valign="top">The field is ignored. Field ignored indicates
that data does not have to be supplied. However, the length of data field in
the corresponding variable length record needs to be set to the correct
length.</td>
</tr>
<tr>
<td align="left" valign="top"><sup>2</sup></td>
<td align="left" valign="top">The field is a required search value.</td>
</tr>
<tr>
<td align="left" valign="top"><sup>3</sup></td>
<td align="left" valign="top">The resource name that is returned is for the
first port on the I/O adapter in card position B of the first multifunction IOP
on the bus.</td>
</tr>
</table>
</td>
</tr>
</table>
<p><strong>Handle.</strong> The value of the handle. The handle allows repeated
calls to obtain more than one resource name that meets the request criteria.
The handle is created through the Create Handle (QRZCRTH) API. The handle is
required in conjunction with the first/next search request. The handle must be
set to binary zeros in conjunction with the first search request when no next
search request is needed. The user is responsible for deleting the handle when
it is no longer needed. Use the Delete Handle (QRZDLTH) API to delete the
handle.</p>
<p><strong>Key.</strong> The key identifies the search criteria. Following are
the key values that can be used:</p>
<table cellpadding="5">
<!-- cols="5 95" -->
<tr>
<td align="left" valign="top"><em>-1</em></td>
<td align="left" valign="top">Search on all hardware resources. This key must
not be used with any other key or an error will result.</td>
</tr>
<tr>
<td align="left" valign="top"><em>1</em></td>
<td align="left" valign="top">Type number of a hardware resource.</td>
</tr>
<tr>
<td align="left" valign="top"><em>2</em></td>
<td align="left" valign="top">Model number of a hardware resource.</td>
</tr>
<tr>
<td align="left" valign="top"><em>4</em></td>
<td align="left" valign="top">Serial number of a hardware resource. The serial
number must be in the form of <em>xx-nnnnnnn</em>, where <em>xx</em> is the
plant of manufacture, dash (required), and <em>nnnnnnn</em> can be a
5-character serial number that is padded on the right with 2 blanks or a fully
qualified 7-character serial number.</td>
</tr>
<tr>
<td align="left" valign="top"><em>6</em></td>
<td align="left" valign="top">Resource name of the system. This key must not be
used with any other key or an error will result.</td>
</tr>
<tr>
<td align="left" valign="top"><em>7</em></td>
<td align="left" valign="top">Bus number of a hardware resource.</td>
</tr>
<tr>
<td align="left" valign="top"><em>8</em></td>
<td align="left" valign="top">Controller storage hardware resource.</td>
</tr>
<tr>
<td align="left" valign="top"><em>9</em></td>
<td align="left" valign="top">Controller workstation hardware resource.</td>
</tr>
<tr>
<td align="left" valign="top"><em>10</em></td>
<td align="left" valign="top">Controller communications hardware resource.</td>
</tr>
<tr>
<td align="left" valign="top"><em>11</em></td>
<td align="left" valign="top">IOP storage hardware resource.</td>
</tr>
<tr>
<td align="left" valign="top"><em>12</em></td>
<td align="left" valign="top">IOP workstation hardware resource.</td>
</tr>
<tr>
<td align="left" valign="top"><em>13</em></td>
<td align="left" valign="top">IOP communications hardware resource.</td>
</tr>
<tr>
<td align="left" valign="top"><em>14</em></td>
<td align="left" valign="top">Control panel hardware resource. This key must
not be used with any other key or an error will result.</td>
</tr>
<tr>
<td align="left" valign="top"><em>15</em></td>
<td align="left" valign="top">Service processor hardware resource. This key
must not be used with any other key or an error will result.</td>
</tr>
<tr>
<td align="left" valign="top"><em>16</em></td>
<td align="left" valign="top">Bus controller hardware resource. This key must
not be used with any other key or an error will result.</td>
</tr>
<tr>
<td align="left" valign="top"><em>17</em></td>
<td align="left" valign="top">Memory card hardware resource. This key must not
be used with any other key or an error will result.</td>
</tr>
<tr>
<td align="left" valign="top"><em>18</em></td>
<td align="left" valign="top">Console controller hardware resource. This key
must not be used with any other key or an error will result.</td>
</tr>
<tr>
<td align="left" valign="top"><em>19</em></td>
<td align="left" valign="top">Console device hardware resource. This key must
not be used with any other key or an error will result.</td>
</tr>
<tr>
<td align="left" valign="top"><em>20</em></td>
<td align="left" valign="top">Main processor hardware resource. This key must
not be used with any other key or an error will result.</td>
</tr>
<tr>
<td align="left" valign="top"><em>21</em></td>
<td align="left" valign="top">System hardware resource.</td>
</tr>
<tr>
<td align="left" valign="top"><em>24</em></td>
<td align="left" valign="top">IOP SOC hardware resource.</td>
</tr>
<tr>
<td align="left" valign="top"><em>25</em></td>
<td align="left" valign="top">Electronic-customer-support communications
resource.</td>
</tr>
<tr>
<td align="left" valign="top"><em>26</em></td>
<td align="left" valign="top">Primary-console-controller hardware resource.
This key must not be used with any other key or an error will result.</td>
</tr>
<tr>
<td align="left" valign="top"><em>27</em></td>
<td align="left" valign="top">IOP cryptographic hardware resource.</td>
</tr>
<tr>
<td align="left" valign="top"><em>28</em></td>
<td align="left" valign="top">IOA cryptographic hardware resource.</td>
</tr>
<tr>
<td align="left" valign="top"><em>29</em></td>
<td align="left" valign="top">Cryptographic device hardware resource. This key
must not be used with any other key or an error will result.</td>
</tr>
<tr>
<td align="left" valign="top"><em>30</em></td>
<td align="left" valign="top">Processor capacity card. This key must not be
used with any other key or an error will result.</td>
</tr>
<tr>
<td align="left" valign="top"><em>31</em></td>
<td align="left" valign="top">Interactive card. This key must not be used with
any other key or an error will result.</td>
</tr>
</table>
<p><strong>Length of data.</strong> The number of bytes for the corresponding
data field. For each field length, see the <em>Type</em> column of the table in
<a href="#HDRSCHECRT">Format of the Resource Criteria</a>.</p>
<p><strong>Length of structure.</strong> The total length (in bytes) of the
structure provided, which includes this field through the end of the last
variable length record.</p>
<p><strong>Number of variable length records.</strong> The number of variable
length records supplied.</p>
<p><strong>Offset to first variable length record.</strong> The value (in
bytes) from the beginning of the structure to the offset field of the first
variable length record.</p>
<p><strong>Search request.</strong> Whether the search request is a first
attempt or a next attempt.</p>
<table cellpadding="5">
<!-- cols="5 95" -->
<tr>
<td align="left" valign="top"><em>1</em></td>
<td align="left" valign="top">The first attempt to obtain a resource name from
a possible list of resource names. Search for the first list entry.</td>
</tr>
<tr>
<td align="left" valign="top"><em>2</em></td>
<td align="left" valign="top">The next attempt to obtain a resource name from a
possible list of resource names. Search for any subsequent list entry if it
exists.</td>
</tr>
</table>
<p><strong>Search resource.</strong> Whether to search for the resource name
from the logical resource information or the packaging resource
information.</p>
<table cellpadding="5">
<!-- cols="5 95" -->
<tr>
<td align="left" valign="top"><em>1</em></td>
<td align="left" valign="top">The logical resource information is searched. The
logical resource information is the vital product data (VPD).</td>
</tr>
<tr>
<td align="left" valign="top"><em>2</em></td>
<td align="left" valign="top">The packaging resource information is searched.
The packaging resource information is the location data. This value is only
valid with key -1, search all hardware resources.</td>
</tr>
</table>
<p><strong>Size of variable length record.</strong> The displacement from the
current record to the next variable length record.</p>
<p><strong>Variable length records.</strong> Each possible variable length
record consists of the size of the variable length record, a key value, the
length of the data, and the data.</p>
<br>
<h3>Error Messages</h3>
<table width="100%" cellpadding="5">
<!-- cols="15 85" -->
<tr>
<th align="left" valign="top" nowrap>Message ID</th>
<th align="left" valign="top">Error Message Text</th>
</tr>
<tr>
<td align="left" valign="top">CPF0B3B E</td>
<td align="left" valign="top">Resource name not found.</td>
</tr>
<tr>
<td align="left" valign="top">CPF0B3C E</td>
<td align="left" valign="top">Search resource &amp;1 is not valid with key
&amp;2.</td>
</tr>
<tr>
<td align="left" valign="top">CPF0B3F E</td>
<td align="left" valign="top">The reserved area is not set to binary
zeros.</td>
</tr>
<tr>
<td align="left" valign="top">CPF0B33 E</td>
<td align="left" valign="top">The handle is not valid.</td>
</tr>
<tr>
<td align="left" valign="top">CPF0B34 E</td>
<td align="left" valign="top">The handle is in wrong state for operation.</td>
</tr>
<tr>
<td align="left" valign="top">CPF0B38 E</td>
<td align="left" valign="top">Resource information not valid.</td>
</tr>
<tr>
<td align="left" valign="top">CPF0B45 E</td>
<td align="left" valign="top">Materialize request is not applicable to resource
&amp;1.</td>
</tr>
<tr>
<td align="left" valign="top">CPF0B46 E</td>
<td align="left" valign="top">Materialize failed.</td>
</tr>
<tr>
<td align="left" valign="top">CPF24B4 E</td>
<td align="left" valign="top">Severe error while addressing parameter
list.</td>
</tr>
<tr>
<td align="left" valign="top">CPF3C19 E</td>
<td align="left" valign="top">Error occurred with receiver variable
specified.</td>
</tr>
<tr>
<td align="left" valign="top">CPF3C82 E</td>
<td align="left" valign="top">Key &amp;1 not valid for API &amp;2.</td>
</tr>
<tr>
<td align="left" valign="top">CPF3C90 E</td>
<td align="left" valign="top">Literal value cannot be changed.</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">CPF9872 E</td>
<td align="left" valign="top">Program or service program &amp;1 in library
&amp;2 ended. Reason code &amp;3.</td>
</tr>
</table>
<br>
<hr>
API introduced: V3R6
<hr>
<table align="center" cellpadding="2" cellspacing="2">
<tr align="center">
<td valign="middle" align="center"><a href="#Top_Of_Page">Top</a> | <a href=
"config.htm">Configuration APIs</a> | <a href="aplist.htm">API by
category</a></td>
</tr>
</table>
</body>
</html>
Reference in New Issue Copy Permalink