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

532 lines
15 KiB
HTML
Raw Permalink 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>Retrieve DASD Management Status (QYASRDMS) 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. -->
<!-- Change History: -->
<!-- YYMMDD USERID Change description -->
<!-- File cleanup completed Oct 2001 by v2cdijab -->
<!-- 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>Retrieve DASD Management Status (QYASRDMS) 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%">Receiver variable</td>
<td align="left" valign="top" width="20%">Output</td>
<td align="left" valign="top" width="20%">Char(*)</td>
</tr>
<tr>
<td align="center" valign="top">2</td>
<td align="left" valign="top">Length of receiver variable</td>
<td align="left" valign="top">Input</td>
<td align="left" valign="top">Binary(4)</td>
</tr>
<tr>
<td align="center" valign="top">3</td>
<td align="left" valign="top">Format name</td>
<td align="left" valign="top">Input</td>
<td align="left" valign="top">Char(8)</td>
</tr>
<tr>
<td align="center" valign="top">4</td>
<td align="left" valign="top">Session handle</td>
<td align="left" valign="top">Input</td>
<td align="left" valign="top">Char(8)</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;Default Public Authority: *USE<br>
<!-- iddvc RMBR -->
<br>
&nbsp;&nbsp;Threadsafe: Yes<br>
<!-- iddvc RMBR -->
<br>
</div>
<p>The Retrieve DASD Management Status (QYASRDMS) API retrieves status
information for the currently active disk management session that was started
using the Start DASD Management Session (QYASSDMS) API.</p>
<br>
<h3><a name="Header_2">Authorities and Locks</a></h3>
<p>None.</p>
<br>
<h3>Required Parameter Group</h3>
<dl>
<dt><strong>Receiver variable</strong></dt>
<dd>OUTPUT; CHAR(*)
<p>The receiver variable that is to receive the disk management status
information from the Retrieve DASD Management Status (QYASRDMS) API.</p>
</dd>
<dt><strong>Length of receiver variable</strong></dt>
<dd>INPUT; BINARY(4)
<p>The length of the receiver variable, in bytes. The minimum length is 8
bytes. If the length of the receiver variable is not large enough to hold all
repeating fields of the format name specified in the Format name parameter,
then no repeating fields are returned. If the length of the receiver variable
is not large enough to hold all non-repeating fields of the beginning portion
of the format (format header), then only the first 8 bytes are returned.</p>
</dd>
<dt><strong>Format name</strong></dt>
<dd>INPUT; CHAR(8)
<p>The format of the information that is returned from the Retrieve DASD
Management Status (QYASRDMS) API. The DMST0100 format is used by this API for
the receiver variable. For a detailed description of the format, see
<a href="#HDRDMSTFMT">Format Descriptions</a>.</p>
</dd>
<dt><strong>Session handle</strong></dt>
<dd>INPUT; CHAR(8)
<p>The unique ID that was returned to the caller on a preceding Start DASD
Management Session (QYASSDMS) API. The session handle contains arbitrary binary
data and should not be interpreted as character data.</p>
<p>Use binary zeroes to retrieve status information for the current or most
recent disk management session when the caller has not started a disk
management session using the Start DASD Management Session (QYASSDMS) API.</p>
<p>Use the session handle when the caller has successfully started a disk
management session using the Start DASD Management (QYASSDMS) API.</p>
<p>If the session handle is not used to perform an operation using the QYASSDMO
API or is not used to check the status of an operation using this API within 5
minutes after a session has been started or an operation has completed, the
session of the associated handle will end and the associated handle will be
invalidated if a call is made to start another disk management session.</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="HDRDMSTFMT">Format Descriptions</a></h3>
<h4>DMST0100 Format</h4>
<p>The following shows the information returned for the DMST0100 format. For
detailed descriptions of the fields in the table, see
<a href="#HDRDMST0100FLD">Field Descriptions</a>.</p>
<table border="1" 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%">Bytes returned</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">Bytes available</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">Session status</td>
</tr>
<tr>
<td align="center" valign="top">12</td>
<td align="center" valign="top">C</td>
<td align="left" valign="top">BINARY(4)</td>
<td align="left" valign="top">Operation identifier of the current or most
recent operation performed</td>
</tr>
<tr>
<td align="center" valign="top">16</td>
<td align="center" valign="top">10</td>
<td align="left" valign="top">BINARY(4)</td>
<td align="left" valign="top">Percentage of operation complete</td>
</tr>
<tr>
<td align="center" valign="top">20</td>
<td align="center" valign="top">14</td>
<td align="left" valign="top">BINARY(4)</td>
<td align="left" valign="top">Offset to error data records</td>
</tr>
<tr>
<td align="center" valign="top">24</td>
<td align="center" valign="top">18</td>
<td align="left" valign="top">BINARY(4)</td>
<td align="left" valign="top">Number of error data records</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">Length of an error data record</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">Reserved</td>
</tr>
<tr>
<td align="left" valign="top" colspan="4"><strong>NOTE:</strong> The following
fields repeat the number of time specified in the number of error data records
field in order of occurrence.</td>
</tr>
<tr>
<td align="center" valign="top" colspan="2">&nbsp;</td>
<td align="left" valign="top">CHAR(7)</td>
<td align="left" valign="top">Error ID</td>
</tr>
<tr>
<td align="center" valign="top" colspan="2">&nbsp;</td>
<td align="left" valign="top">CHAR(30)</td>
<td align="left" valign="top">Error data</td>
</tr>
</table>
<br>
<br>
<h3><a name="HDRDMST0100FLD">Field Descriptions</a></h3>
<strong>Bytes available.</strong> The number of bytes of data available to be
returned. All available data is returned if enough space is provided.
<p><strong>Bytes returned.</strong> The number of bytes of data returned.</p>
<p><strong>Error data.</strong> The data related to the error ID associated
with the action identifier.</p>
<p><strong>Error ID.</strong> The 7-character error code ID of the most
recently completed action associated to the session handle. Possible error code
IDs returned are:</p>
<table cellpadding="5">
<!-- cols="15 85" -->
<tr>
<td align="left" valign="top"><em>CPFBA23</em></td>
<td align="left" valign="top">Operation failed.</td>
</tr>
<tr>
<td align="left" valign="top"><em>CPFBA25</em></td>
<td align="left" valign="top">A general DASD management error has
occurred.</td>
</tr>
<tr>
<td align="left" valign="top"><em>CPFBA27</em></td>
<td align="left" valign="top">Could not restore mirrored data.</td>
</tr>
<tr>
<td align="left" valign="top"><em>CPFBA31</em></td>
<td align="left" valign="top">Disk unit &amp;1 has errors.</td>
</tr>
<tr>
<td align="left" valign="top"><em>CPFBA3A</em></td>
<td align="left" valign="top">Create new ASP failed.</td>
</tr>
<tr>
<td align="left" valign="top"><em>CPFBA3F</em></td>
<td align="left" valign="top">Cannot rebuild parity information.</td>
</tr>
<tr>
<td align="left" valign="top"><em>CPFBA41</em></td>
<td align="left" valign="top">Device parity set not operational.</td>
</tr>
<tr>
<td align="left" valign="top"><em>CPIBA20</em></td>
<td align="left" valign="top">Operation was ended.</td>
</tr>
<tr>
<td align="left" valign="top"><em>CPIBA21</em></td>
<td align="left" valign="top">Parity set needs intervention.</td>
</tr>
</table>
<p><strong>Length of an error data record</strong> The total number of bytes of
an individual error data record.</p>
<p><strong>Number of error data records</strong> The number of error data
records specified in the array of error data records.</p>
<p><strong>Offset to error data records.</strong> The offset in bytes from the
start of the receiver variable to the first error data record.</p>
<p><strong>Operation identifier of current or most recent operation
performed.</strong> If the session status is 'session is active and currently
performing an operation,' then this field indicates the current operation being
performed associated to the session handle. Otherwise, this field indicates the
operation most recently completed associated to the session handle.</p>
<p>Valid operation key values are:</p>
<table cellpadding="5">
<!-- cols="5 95" -->
<tr>
<td align="left" valign="top"><em>1</em></td>
<td align="left" valign="top">Change the storage threshold percentage of an
ASP</td>
</tr>
<tr>
<td align="left" valign="top"><em>2</em></td>
<td align="left" valign="top">Add disk units to an ASP</td>
</tr>
<tr>
<td align="left" valign="top"><em>3</em></td>
<td align="left" valign="top">Suspend mirrored protection on a disk unit</td>
</tr>
<tr>
<td align="left" valign="top"><em>4</em></td>
<td align="left" valign="top">Resume mirrored protection on a disk unit</td>
</tr>
<tr>
<td align="left" valign="top"><em>5</em></td>
<td align="left" valign="top">Include disk unit in device parity
protection</td>
</tr>
<tr>
<td align="left" valign="top"><em>6</em></td>
<td align="left" valign="top">Rebuild data on a disk unit after a parity
fault</td>
</tr>
<tr>
<td align="left" valign="top"><em>7</em></td>
<td align="left" valign="top">Replace mirrored disk unit</td>
</tr>
<tr>
<td align="left" valign="top"><em>8</em></td>
<td align="left" valign="top">Start device parity protection on a controller
with no configured disk units</td>
</tr>
<tr>
<td align="left" valign="top"><em>9</em></td>
<td align="left" valign="top">Enable remote load source mirroring</td>
</tr>
<tr>
<td align="left" valign="top"><em>10</em></td>
<td align="left" valign="top">Disable remote load source mirroring</td>
</tr>
<tr>
<td align="left" valign="top"><em>11</em></td>
<td align="left" valign="top">Power off a disk unit</td>
</tr>
<tr>
<td align="left" valign="top"><em>12</em></td>
<td align="left" valign="top">Power on a disk unit</td>
</tr>
<tr>
<td align="left" valign="top"><em>13</em></td>
<td align="left" valign="top">Format a disk unit</td>
</tr>
<tr>
<td align="left" valign="top"><em>14</em></td>
<td align="left" valign="top">Clear a disk unit</td>
</tr>
<tr>
<td align="left" valign="top"><em>15</em></td>
<td align="left" valign="top">Scan surface of a disk unit</td>
</tr>
<tr>
<td align="left" valign="top"><em>5000</em></td>
<td align="left" valign="top">Active DST/Service Tools operations</td>
</tr>
<tr>
<td align="left" valign="top"><em>5001</em></td>
<td align="left" valign="top">No operations have been performed</td>
</tr>
<tr>
<td align="left" valign="top"><em>5002</em></td>
<td align="left" valign="top">Specified handle not performing an operation</td>
</tr>
</table>
<p><strong>Percentage operation complete.</strong> If the session status is
'session is active and currently performing an operation' of the session
indicated by the session handle parameter, then this field indicates, on a
scale of 0 to 100, the percentage of completion of the current operation being
performed.</p>
<p><strong>Session status.</strong> The status of the session indicated by the
session handle parameter. Session status values are:</p>
<table cellpadding="5">
<!-- cols="5 95" -->
<tr>
<td align="left" valign="top"><em>0</em></td>
<td align="left" valign="top">Session is active and not currently performing an
operation</td>
</tr>
<tr>
<td align="left" valign="top"><em>1</em></td>
<td align="left" valign="top">Session was ended</td>
</tr>
<tr>
<td align="left" valign="top"><em>2</em></td>
<td align="left" valign="top">Session is active and currently performing an
operation</td>
</tr>
<tr>
<td align="left" valign="top"><em>3</em></td>
<td align="left" valign="top">Session is in error</td>
</tr>
</table>
<br>
<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 align="left" valign="top" width="15%">CPF3C21 E</td>
<td align="left" valign="top" width="85%">Format name &amp;1 is not valid.</td>
</tr>
<tr>
<td align="left" valign="top">CPF3C24 E</td>
<td align="left" valign="top">Length of the receiver variable is not
valid.</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">CPF3C36 E</td>
<td align="left" valign="top">Number of parameters, &amp;1, entered for this
API was not valid.</td>
</tr>
</table>
<br>
<hr>
API introduced: V4R5
<hr>
<center>
<table 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">APIs by category</a></td>
</tr>
</table>
</center>
</body>
</html>