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

705 lines
20 KiB
HTML
Raw Permalink Blame History

<!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>Control Device (QTACTLDV) 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. -->
<!-- QTACTLDV SCRIPT A converted by B2H R4.1 (346) (CMS) by KENTALA -->
<!-- at RCHVMW2 on 21 Oct 1998 at 18:23:34 -->
<!-- Change History: -->
<!-- YYMMDD USERID Change description -->
<!-- 050504 LANA Added new reason code for FMR tape -->
<!-- File cleanup completed on 6/29/01 -->
<!--End Header Records -->
<link rel="stylesheet" type="text/css" href="../rzahg/ic.css">
</head>
<body>
<!-- Java sync-link -->
<script type="text/javascript" language="Javascript" src="../rzahg/synch.js">
</script>
<a name="top"></a>
<h2>Control Device (QTACTLDV) 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%">Device name</td>
<td align="left" valign="top" width="20%">Input</td>
<td align="left" valign="top" width="20%">Char(10)</td>
</tr>
<tr>
<td align="center" valign="top">2</td>
<td align="left" valign="top">Requested function</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">Send buffer</td>
<td align="left" valign="top">Input</td>
<td align="left" valign="top">Char(*)</td>
</tr>
<tr>
<td align="center" valign="top">4</td>
<td align="left" valign="top">Length of send buffer</td>
<td align="left" valign="top">Input</td>
<td align="left" valign="top">Binary(4)</td>
</tr>
<tr>
<td align="center" valign="top">5</td>
<td align="left" valign="top">Receive buffer</td>
<td align="left" valign="top">Output</td>
<td align="left" valign="top">Char(*)</td>
</tr>
<tr>
<td align="center" valign="top">6</td>
<td align="left" valign="top">Length of receive buffer</td>
<td align="left" valign="top">Input</td>
<td align="left" valign="top">Binary(4)</td>
</tr>
<tr>
<td align="center" valign="top">7</td>
<td align="left" valign="top">Command format</td>
<td align="left" valign="top">Input</td>
<td align="left" valign="top">Char(8)</td>
</tr>
<tr>
<td align="center" valign="top">8</td>
<td align="left" valign="top">Command data</td>
<td align="left" valign="top">Input</td>
<td align="left" valign="top">Char(*)</td>
</tr>
<tr>
<td align="center" valign="top">9</td>
<td align="left" valign="top">Length of command data</td>
<td align="left" valign="top">Input</td>
<td align="left" valign="top">Binary(4)</td>
</tr>
<tr>
<td align="center" valign="top">10</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: Conditional; see <a href="#Header_8">Usage Notes</a>.<br>
<!-- iddvc RMBR -->
<br>
</div>
<p>The Control Device (QTACTLDV) API provides a direct command interface to a
device. The caller of this API can issue any command directly to a device and
transfer data to or from the device.</p>
<p><strong>Note:</strong> For tape devices, the Retrieve Device Capabilities
(QTARDCAP) API can be used to determine if the tape device supports the
QTACTLDV API. Other kinds of devices currently do not support this API. This
API can be used for a tape device within a media library if the device is
deallocated from the library.</p>
<p><strong>Note:</strong> Incorrect use of this API can cause damage to data
saved on tape media or can interfere with I/O processor function.</p>
<br>
<h3><a name="Header_2">Authorities and Locks</a></h3>
<dl>
<dt><em>API Public Authority</em></dt>
<dd>*EXCLUDE</dd>
<dt><em>Special Authority</em></dt>
<dd>*SERVICE</dd>
<dt><em>Device Description Authority</em></dt>
<dd>*CHANGE</dd>
<dt><em>Device Description Lock</em></dt>
<dd>*EXCLRD</dd>
</dl>
<br>
<h3><a name="Header_3">Required Parameter Group</a></h3>
<dl>
<dt><strong>Device name</strong></dt>
<dd>INPUT; CHAR(10)
<p>The device description to which the request is sent.</p>
</dd>
<dt><strong>Requested function</strong></dt>
<dd>INPUT; BINARY(4)
<p>The function to perform. The possible values are:</p>
<table cellpadding="5">
<!-- cols="5 95" -->
<tr>
<td align="left" valign="top"><em>1</em></td>
<td align="left" valign="top">Open a connection to the device. This function
must be performed before any commands can be sent to the device. The device
must be varied on before this function is performed. No other job can use the
device while the connection is open.</td>
</tr>
<tr>
<td align="left" valign="top"><em>2</em></td>
<td align="left" valign="top">Send a command to the device. When running in a
multithreaded environment, a command sent by a thread must be complete before
another command can be sent by another thread.</td>
</tr>
<tr>
<td align="left" valign="top"><em>3</em></td>
<td align="left" valign="top">Close the connection to the device. This function
must be performed after the user has completed sending commands to the device.
No other job can use the device until the connection is closed.</td>
</tr>
</table>
</dd>
<dt><strong>Send buffer</strong></dt>
<dd>INPUT; CHAR(*)
<p>A buffer containing data to send to the device when a data transfer command
is sent. No support is provided to send and receive data on the same
command.</p>
<p>This parameter is ignored if the length of the send buffer is 0.</p>
</dd>
<dt><strong>Length of send buffer</strong></dt>
<dd>INPUT; BINARY(4)
<p>The length of the send buffer.</p>
<p>This parameter must be 0 for the open connection and close connection
functions.</p>
</dd>
<dt><strong>Receive buffer</strong></dt>
<dd>OUTPUT; CHAR(*)
<p>A buffer to store data received from the device after a data transfer
command is sent. No support is provided to send and receive data on the same
command.</p>
<p>This parameter is ignored if the length of the receive buffer is 0.</p>
</dd>
<dt><strong>Length of receive buffer</strong></dt>
<dd>INPUT; BINARY(4)
<p>The length of the receive buffer.</p>
<p>This parameter must be 0 for the open connection and close connection
functions.</p>
</dd>
<dt><strong>Command format</strong></dt>
<dd>INPUT; CHAR(8)
<p>The format of the command data. The following format is supported.</p>
<dl>
<dt><em>CTLD0100</em></dt>
<dd>Issue command to a tape device.</dd>
</dl>
<p><strong>Note:</strong> The connection must be opened using the open function
before a command can be issued to the device.</p>
<p>See <a href="#HDRTAPIO1">CTLD0100 Format</a> for more information on the
command data format.</p>
</dd>
<dt><strong>Command data</strong></dt>
<dd>INPUT; CHAR(*)
<p>The variable that contains the command data.</p>
<p>This parameter is ignored if the length of command data is set to 0.</p>
</dd>
<dt><strong>Length of command data</strong></dt>
<dd>INPUT; BINARY(4)
<p>The length of the command data to be sent to the device. The command data
must be 0, or a minimum of 32 bytes long and a maximum of 56 bytes long.</p>
<p>This parameter must be 0 for the open connection and close connection
functions.</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="HDRTAPIO1">CTLD0100 Format</a></h3>
<p>The following table shows the command information that is required for the
CTLD0100 format. For more details about the fields in the following table, see
<a href="#HDRFLD01">Field Descriptions</a>.<br>
</p>
<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%">Data transfer direction</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">Requested transfer length</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">Ignore length errors</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">Command timeout value</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">Type of command</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 command string</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">Length of command string</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">Reserved</td>
</tr>
<tr>
<td align="center" valign="top"><br>
</td>
<td align="center" valign="top"><br>
</td>
<td align="left" valign="top">CHAR(*)</td>
<td align="left" valign="top">Command string</td>
</tr>
</table>
<br><br>
<h3><a name="HDRFLD01">Field Descriptions</a></h3>
<p><strong>Command string.</strong> The command string to send to the device.
See the device specifications to determine what command strings are supported
by the device.</p>
<p><strong>Command timeout value.</strong> The time, in seconds, to wait for
the command to complete. Valid values are 1 through 7200.</p>
<p><strong>Data transfer direction.</strong> The direction of any data transfer
associated with the command. The possible values are:</p>
<table cellpadding="5">
<!-- cols="5 95" -->
<tr>
<td align="left" valign="top"><em>0</em></td>
<td align="left" valign="top">No data transfer.</td>
</tr>
<tr>
<td align="left" valign="top"><em>1</em></td>
<td align="left" valign="top">Receive data from the device.</td>
</tr>
<tr>
<td align="left" valign="top"><em>2</em></td>
<td align="left" valign="top">Send data to the device.</td>
</tr>
</table>
<p><strong>Ignore length errors.</strong> The possible values are:</p>
<table cellpadding="5">
<!-- cols="5 95" -->
<tr>
<td align="left" valign="top"><em>0</em></td>
<td align="left" valign="top">Report length errors.</td>
</tr>
<tr>
<td align="left" valign="top"><em>1</em></td>
<td align="left" valign="top">Ignore length errors.</td>
</tr>
</table>
<p><strong>Length of command string.</strong> The length of the command string
to send to the device. Valid values are 0 through 24.</p>
<p><strong>Offset to command string.</strong> The offset from the start of the
command data, in bytes, to the start of the command string. Valid values are 32
and greater.</p>
<p><strong>Requested transfer length.</strong> The expected length of the data
to be transferred by the command. The requested transfer length must be less
than or equal to the length of the buffer parameter that will be used to send
or receive the data.</p>
<p><strong>Note:</strong> This field must be 0 for commands with no data
transfer.</p>
<p><strong>Reserved.</strong> An ignored field. This value must be set to
0.</p>
<p><strong>Type of Command.</strong> The type of command. The possible values
are:</p>
<table cellpadding="5">
<!-- cols="5 95" -->
<tr>
<td align="left" valign="top"><em>0</em></td>
<td align="left" valign="top">Small Computer System Interface (SCSI)
command.</td>
</tr>
<tr>
<td align="left" valign="top"><em>1</em></td>
<td align="left" valign="top">Reset the device.</td>
</tr>
</table>
<br><br>
<h3><a name="Header_6">Error Messages</a></h3>
<p>For descriptions of the reason codes in CPF67C8, see <a href="#HDRRC1">
Reason Codes</a>.</p>
<br>
<table width="100%">
<!-- 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">CPF222E E</td>
<td width="85%" valign="top">&amp;1 special authority is required.</td>
</tr>
<tr>
<td valign="top">CPF24B4 E</td>
<td valign="top">Severe error while addressing parameter list.</td>
</tr>
<tr>
<td valign="top">CPF3C1D E</td>
<td valign="top">Length specified in parameter &amp;1 not valid.</td>
</tr>
<tr>
<td valign="top">CPF3C21 E</td>
<td valign="top">Format name &amp;1 is not valid.</td>
</tr>
<tr>
<td valign="top">CPF3C39 E</td>
<td valign="top">Value for reserved field not valid.</td>
</tr>
<tr>
<td valign="top">CPF3C3C E</td>
<td valign="top">Value for parameter &amp;1 not valid.</td>
</tr>
<tr>
<td valign="top">CPF3C4C E</td>
<td valign="top">Value not valid for field &amp;1.</td>
</tr>
<tr>
<td valign="top">CPF3C90 E</td>
<td valign="top">Literal value cannot be changed.</td>
</tr>
<tr>
<td valign="top">CPF3CF1 E</td>
<td valign="top">Error code parameter not valid.</td>
</tr>
<tr>
<td valign="top">CPF3CF2 E</td>
<td valign="top">Error(s) occurred during running of &amp;1 API.</td>
</tr>
<tr>
<td valign="top">CPF6708 E</td>
<td valign="top">Command ended due to error.</td>
</tr>
<tr>
<td valign="top">CPF67C8 E</td>
<td valign="top">Command failed for device &amp;1. Reason code &amp;2.</td>
</tr>
<tr>
<td valign="top">CPF9814 E</td>
<td valign="top">Device &amp;1 not found.</td>
</tr>
<tr>
<td valign="top">CPF9872 E</td>
<td valign="top">Program or service program &amp;1 in library &amp;2 ended.
Reason code &amp;3.</td>
</tr>
</table>
<br><br>
<h3><a name="HDRRC1">Reason Codes</a></h3>
<p>This topic contains the description of the reason codes returned in message
CPF67C8.</p>
<p><strong>Note:</strong> For command timeouts, I/O processor errors, system
bus errors, and device bus errors, a reset operation might occur on the device
bus. Other devices attached to the same bus may be affected by this reset
operation.</p>
<p>Possible reason code values are:</p>
<table cellpadding="5">
<!-- cols="15 85" -->
<tr>
<td align="left" valign="top"><em>'010300'x</em></td>
<td align="left" valign="top">Command length not valid: The command length was
too long for existing device interface specifications.</td>
</tr>
<tr>
<td align="left" valign="top"><em>'010700'x</em></td>
<td align="left" valign="top">Data length not valid: The IOP does not support
the size of the data transfer. Use the Retrieve Device Capabilities (QTARDCAP)
API to determine the maximum block size supported.</td>
</tr>
<tr>
<td align="left" valign="top"><em>'020900'x</em></td>
<td align="left" valign="top">Insufficient data: The data transfer buffer is
not large enough.</td>
</tr>
<tr>
<td align="left" valign="top"><em>'02C0yy'x</em></td>
<td align="left" valign="top">Device detected error: The tape device reported
an error condition. For an SCSI type of command, yy is set to the value of the
completion status.</td>
</tr>
<tr>
<td align="left" valign="top"><em>'02C100'x</em></td>
<td align="left" valign="top">Selection timeout: The tape device did not
respond to the command. Check device power and cables and retry the command. If
the problem persists, contact your hardware service provider.</td>
</tr>
<tr>
<td align="left" valign="top"><em>'02C200'x</em></td>
<td align="left" valign="top">I/O processor length error: Length error on the
data transfer. The ignore length errors field was not set in the command
data.</td>
</tr>
<tr>
<td align="left" valign="top"><em>'02C300'x</em></td>
<td align="left" valign="top">I/O processor error: The I/O processor card
detected an internal hardware failure. Contact your hardware service
provider.</td>
</tr>
<tr>
<td align="left" valign="top"><em>'02C400'x</em></td>
<td align="left" valign="top">Command timed out: The tape device did not
complete the requested command within the specified time. Correct the command
timeout value and retry the command. If the problem persists, contact your
hardware service provider.</td>
</tr>
<tr>
<td align="left" valign="top"><em>'02C500'x</em></td>
<td align="left" valign="top">System bus error: The host internal system bus
failed. Contact your hardware service provider.</td>
</tr>
<tr>
<td align="left" valign="top"><em>'02C600'x</em></td>
<td align="left" valign="top">Device bus error: The I/O processor detected a
failure in the device interface. Check the device power and cables and retry
the command. If the problem persists, contact your hardware service
provider.</td>
</tr>
<tr>
<td align="left" valign="top">
<img src="delta.gif" alt="Start of change"><em>'02C700'x</em></td>
<td align="left" valign="top">Device detected error: The device rejected a
microcode update. <img src="deltaend.gif" alt="End of change"></td>
</tr>
<tr>
<td align="left" valign="top"><em>'100000'x</em></td>
<td align="left" valign="top">Open failure: A connection could not be opened to
the device. The device may not be varied on or is being used by another
job.</td>
</tr>
<tr>
<td align="left" valign="top"><em>'100001'x</em></td>
<td align="left" valign="top">Open failure: A connection could not be opened to
the device. The device does not support the QTACTLDV API.</td>
</tr>
<tr>
<td align="left" valign="top"><em>'100002'x</em></td>
<td align="left" valign="top">Open failure: A connection could not be opened to
the device. The device is in a failed state.</td>
</tr>
<tr>
<td align="left" valign="top"><em>'200000'x</em></td>
<td align="left" valign="top">Close failure: The connection to the device could
not be closed. The device may not be varied on or is being used by another
job.</td>
</tr>
<tr>
<td align="left" valign="top"><em>'200002'x</em></td>
<td align="left" valign="top">Close failure: The connection to the device could
not be closed. The device is in a failed state.</td>
</tr>
<tr>
<td align="left" valign="top"><em>'300000'x</em></td>
<td align="left" valign="top">Device not valid: The device specified is not a
tape device.</td>
</tr>
<tr>
<td align="left" valign="top"><em>'300001'x</em></td>
<td align="left" valign="top">Resource not valid: The resource name associated
with the specified device is not valid or does not exist.</td>
</tr>
<tr>
<td align="left" valign="top"><em>'400000'x</em></td>
<td align="left" valign="top">Connection not open: The command could not be
completed because there is not an open connection.</td>
</tr>
</table>
<br><br>
<h3><a name="Header_8">Usage Notes</a></h3>
<p>When running in a multithreaded environment, a command sent by a thread to a
device must be complete before a command can be sent by another thread to the
same device.</p>
<br>
<h3><a name="Header_9">Usage Example</a></h3>
<p>See <a href="../apiref/apiexusdev.htm">Using the QTACTLDV API</a> in API examples for
an example of how to use the QTACTLDV API.</p>
<br>
<hr>
API introduced: V4R4
<hr>
<center>
<table cellpadding="2" cellspacing="2">
<tr align="center">
<td valign="middle" align="center"><a href="#top">Top</a> | <a href=
"misc1.htm">Miscellaneous APIs</a> | <a href="aplist.htm">APIs by
category</a></td>
</tr>
</table>
</center>
</body>
</html>
Reference in New Issue View Git Blame Copy Permalink