984 lines
29 KiB
HTML
984 lines
29 KiB
HTML
|
<!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 Tape Labels (QTARTLBL) 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 on 15 May 2002 by JKOCHAN -->
|
||
|
<!-- Change History: -->
|
||
|
<!-- YYMMDD USERID Change description -->
|
||
|
<!-- 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 Tape Labels (QTARTLBL) API</h2>
|
||
|
|
||
|
<div class="box" style="width: 80%;">
|
||
|
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">Device description</td>
|
||
|
<td align="left" valign="top">Input</td>
|
||
|
<td align="left" valign="top">Char(10)</td>
|
||
|
</tr>
|
||
|
|
||
|
<tr>
|
||
|
<td align="center" valign="top">5</td>
|
||
|
<td align="left" valign="top">Request qualifiers</td>
|
||
|
<td align="left" valign="top">Input</td>
|
||
|
<td align="left" valign="top">Char(*)</td>
|
||
|
</tr>
|
||
|
|
||
|
<tr>
|
||
|
<td align="center" valign="top">6</td>
|
||
|
<td align="left" valign="top">Length of request qualifiers</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">Error code</td>
|
||
|
<td align="left" valign="top">I/O</td>
|
||
|
<td align="left" valign="top">Char(*)</td>
|
||
|
</tr>
|
||
|
</table>
|
||
|
|
||
|
<br>
|
||
|
Default Public Authority: *USE<br>
|
||
|
<!-- iddvc RMBR -->
|
||
|
<br>
|
||
|
Threadsafe: No<br>
|
||
|
<!-- iddvc RMBR -->
|
||
|
<br>
|
||
|
</div>
|
||
|
|
||
|
<p>The Retrieve Tape Labels (QTARTLBL) API retrieves the label information for
|
||
|
the files on a tape cartridge. This API provides a function similar to the
|
||
|
Display Tape (DSPTAP) command.</p>
|
||
|
|
||
|
<h3>Authorities and Locks</h3>
|
||
|
|
||
|
<dl>
|
||
|
<dt><em>Device Description Authority</em></dt>
|
||
|
|
||
|
<dd>*USE</dd>
|
||
|
</dl>
|
||
|
|
||
|
<br>
|
||
|
|
||
|
|
||
|
<h3>Required Parameter Group</h3>
|
||
|
|
||
|
<dl>
|
||
|
<dt><strong>Receiver variable</strong></dt>
|
||
|
|
||
|
<dd>OUTPUT; CHAR(*)
|
||
|
|
||
|
<p>The receiver variable that receives the information requested. You can
|
||
|
specify the size of the area to be smaller than the format requested as long as
|
||
|
you specify the length parameter correctly. As a result, the API returns only
|
||
|
the data that the area can hold.</p>
|
||
|
</dd>
|
||
|
|
||
|
<dt><strong>Length of receiver variable</strong></dt>
|
||
|
|
||
|
<dd>INPUT; BINARY(4)
|
||
|
|
||
|
<p>The length of the receiver variable provided. The length of receiver
|
||
|
variable parameter may be specified up to the size of the receiver variable
|
||
|
specified in the user program. If the length of receiver variable parameter
|
||
|
specified is larger than the allocated size of the receiver variable specified
|
||
|
in the user program, the results are not predictable. The minimum length is 8
|
||
|
bytes.</p>
|
||
|
</dd>
|
||
|
|
||
|
<dt><strong>Format name</strong></dt>
|
||
|
|
||
|
<dd>INPUT; CHAR(8)
|
||
|
|
||
|
<p>The content and format of the information being returned.</p>
|
||
|
|
||
|
<p>The RLBL0100 format must be used for the label information. See <a href=
|
||
|
"#HDRRLBL0100">RLBL0100 Format</a> to view the information returned for this
|
||
|
format.</p>
|
||
|
</dd>
|
||
|
|
||
|
<dt><strong>Device description</strong></dt>
|
||
|
|
||
|
<dd>INPUT; CHAR(10)
|
||
|
|
||
|
<p>The name of the tape device or tape library device containing the cartridge
|
||
|
for which the label information is to be returned.</p>
|
||
|
</dd>
|
||
|
|
||
|
<dt><strong>Request qualifiers</strong></dt>
|
||
|
|
||
|
<dd>INPUT; CHAR(*)
|
||
|
|
||
|
<p>The request qualifiers specify which cartridge to use, what labels to
|
||
|
return, and what action to perform after the label information is retrieved.
|
||
|
The following table shows the information that can be specified. Default values
|
||
|
are used for any fields that are not specified. For more details about the
|
||
|
fields in the following table see <a href="#HDRFLDXX">Field
|
||
|
Descriptions</a>.</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%">CHAR(6)</td>
|
||
|
<td align="left" valign="top" width="60%">Requested volume identifier</td>
|
||
|
</tr>
|
||
|
|
||
|
<tr>
|
||
|
<td align="center" valign="top" width="10%">6</td>
|
||
|
<td align="center" valign="top" width="10%">6</td>
|
||
|
<td align="left" valign="top" width="20%">CHAR(17)</td>
|
||
|
<td align="left" valign="top" width="60%">Requested file label</td>
|
||
|
</tr>
|
||
|
|
||
|
<tr>
|
||
|
<td align="center" valign="top" width="10%">23</td>
|
||
|
<td align="center" valign="top" width="10%">17</td>
|
||
|
<td align="left" valign="top" width="20%">CHAR(10)</td>
|
||
|
<td align="left" valign="top" width="60%">Starting file sequence number</td>
|
||
|
</tr>
|
||
|
|
||
|
<tr>
|
||
|
<td align="center" valign="top" width="10%">33</td>
|
||
|
<td align="center" valign="top" width="10%">21</td>
|
||
|
<td align="left" valign="top" width="20%">CHAR(10)</td>
|
||
|
<td align="left" valign="top" width="60%">Ending file sequence number</td>
|
||
|
</tr>
|
||
|
|
||
|
<tr>
|
||
|
<td align="center" valign="top" width="10%">43</td>
|
||
|
<td align="center" valign="top" width="10%">2B</td>
|
||
|
<td align="left" valign="top" width="20%">CHAR(1)</td>
|
||
|
<td align="left" valign="top" width="60%">End option</td>
|
||
|
</tr>
|
||
|
|
||
|
<tr>
|
||
|
<td align="center" valign="top" width="10%">44</td>
|
||
|
<td align="center" valign="top" width="10%">2C</td>
|
||
|
<td align="left" valign="top" width="20%">CHAR(*)</td>
|
||
|
<td align="left" valign="top" width="60%">Reserved</td>
|
||
|
</tr>
|
||
|
</table>
|
||
|
|
||
|
<br>
|
||
|
<br>
|
||
|
</dd>
|
||
|
|
||
|
<dt><strong>Length of request qualifiers</strong></dt>
|
||
|
|
||
|
<dd>INPUT; BINARY(4)
|
||
|
|
||
|
<p>The length, in bytes, of the Request qualifiers provided. The following
|
||
|
values are allowed:</p>
|
||
|
|
||
|
<table cellpadding="5">
|
||
|
<!-- cols="15 85" -->
|
||
|
<tr>
|
||
|
<td align="left" valign="top"><em>0</em></td>
|
||
|
<td align="left" valign="top">No request qualifiers are provided.</td>
|
||
|
</tr>
|
||
|
|
||
|
<tr>
|
||
|
<td align="left" valign="top"><em>6</em></td>
|
||
|
<td align="left" valign="top">Only the requested volume identifier is
|
||
|
specified.</td>
|
||
|
</tr>
|
||
|
|
||
|
<tr>
|
||
|
<td align="left" valign="top"><em>23</em></td>
|
||
|
<td align="left" valign="top">The requested volume identifier and the requested
|
||
|
file label is specified.</td>
|
||
|
</tr>
|
||
|
|
||
|
<tr>
|
||
|
<td align="left" valign="top"><em>33</em></td>
|
||
|
<td align="left" valign="top">The requested volume identifier, requested file
|
||
|
label, and starting file sequence number is is specified.</td>
|
||
|
</tr>
|
||
|
|
||
|
<tr>
|
||
|
<td align="left" valign="top"><em>43</em></td>
|
||
|
<td align="left" valign="top">The requested volume identifier, requested file
|
||
|
label, starting file sequence number, and ending file sequence number is
|
||
|
specified.</td>
|
||
|
</tr>
|
||
|
|
||
|
<tr>
|
||
|
<td align="left" valign="top"><em>44 or greater</em></td>
|
||
|
<td align="left" valign="top">All request qualifiers are specified.</td>
|
||
|
</tr>
|
||
|
</table>
|
||
|
|
||
|
<br>
|
||
|
<br>
|
||
|
</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="HDRRCTG100">RLBL0100 Format</a></h3>
|
||
|
|
||
|
<p>The following table shows the information that is returned for the RLBL0100
|
||
|
format. For more details about the fields in the following table, see <a href=
|
||
|
"#HDRFLDXX">Field Descriptions</a>.</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%">Bytes returned</td>
|
||
|
</tr>
|
||
|
|
||
|
<tr>
|
||
|
<td align="center" valign="top" width="10%">4</td>
|
||
|
<td align="center" valign="top" width="10%">4</td>
|
||
|
<td align="left" valign="top" width="20%">BINARY(4)</td>
|
||
|
<td align="left" valign="top" width="60%">Bytes available</td>
|
||
|
</tr>
|
||
|
|
||
|
<tr>
|
||
|
<td align="center" valign="top" width="10%">8</td>
|
||
|
<td align="center" valign="top" width="10%">8</td>
|
||
|
<td align="left" valign="top" width="20%">CHAR(10)</td>
|
||
|
<td align="left" valign="top" width="60%">Device name</td>
|
||
|
</tr>
|
||
|
|
||
|
<tr>
|
||
|
<td align="center" valign="top" width="10%">18</td>
|
||
|
<td align="center" valign="top" width="10%">12</td>
|
||
|
<td align="left" valign="top" width="20%">CHAR(6)</td>
|
||
|
<td align="left" valign="top" width="60%">Cartridge ID</td>
|
||
|
</tr>
|
||
|
|
||
|
<tr>
|
||
|
<td align="center" valign="top" width="10%">24</td>
|
||
|
<td align="center" valign="top" width="10%">18</td>
|
||
|
<td align="left" valign="top" width="20%">CHAR(80)</td>
|
||
|
<td align="left" valign="top" width="60%">Volume Label</td>
|
||
|
</tr>
|
||
|
|
||
|
<tr>
|
||
|
<td align="center" valign="top" width="10%">104</td>
|
||
|
<td align="center" valign="top" width="10%">68</td>
|
||
|
<td align="left" valign="top" width="20%">CHAR(1)</td>
|
||
|
<td align="left" valign="top" width="60%">Code</td>
|
||
|
</tr>
|
||
|
|
||
|
<tr>
|
||
|
<td align="center" valign="top" width="10%">105</td>
|
||
|
<td align="center" valign="top" width="10%">69</td>
|
||
|
<td align="left" valign="top" width="20%">CHAR(1)</td>
|
||
|
<td align="left" valign="top" width="60%">Standard label</td>
|
||
|
</tr>
|
||
|
|
||
|
<tr>
|
||
|
<td align="center" valign="top" width="10%">106</td>
|
||
|
<td align="center" valign="top" width="10%">6A</td>
|
||
|
<td align="left" valign="top" width="20%">CHAR(1)</td>
|
||
|
<td align="left" valign="top" width="60%">Leading tape mark</td>
|
||
|
</tr>
|
||
|
|
||
|
<tr>
|
||
|
<td align="center" valign="top" width="10%">107</td>
|
||
|
<td align="center" valign="top" width="10%">6B</td>
|
||
|
<td align="left" valign="top" width="20%">CHAR(10)</td>
|
||
|
<td align="left" valign="top" width="60%">Density</td>
|
||
|
</tr>
|
||
|
|
||
|
<tr>
|
||
|
<td align="center" valign="top">117</td>
|
||
|
<td align="center" valign="top">75</td>
|
||
|
<td align="left" valign="top">CHAR(2)</td>
|
||
|
<td align="left" valign="top">Reserved</td>
|
||
|
</tr>
|
||
|
|
||
|
<tr>
|
||
|
<td align="center" valign="top">119</td>
|
||
|
<td align="center" valign="top">77</td>
|
||
|
<td align="left" valign="top">CHAR(1)</td>
|
||
|
<td align="left" valign="top">Additional label entries</td>
|
||
|
</tr>
|
||
|
|
||
|
<tr>
|
||
|
<td align="center" valign="top">120</td>
|
||
|
<td align="center" valign="top">78</td>
|
||
|
<td align="left" valign="top">BINARY(4)</td>
|
||
|
<td align="left" valign="top">Offset to label information</td>
|
||
|
</tr>
|
||
|
|
||
|
<tr>
|
||
|
<td align="center" valign="top">124</td>
|
||
|
<td align="center" valign="top">7C</td>
|
||
|
<td align="left" valign="top">BINARY(4)</td>
|
||
|
<td align="left" valign="top">Number of label information entries</td>
|
||
|
</tr>
|
||
|
|
||
|
<tr>
|
||
|
<td align="center" valign="top">128</td>
|
||
|
<td align="center" valign="top">80</td>
|
||
|
<td align="left" valign="top">BINARY(4)</td>
|
||
|
<td align="left" valign="top">Length of label information entry</td>
|
||
|
</tr>
|
||
|
|
||
|
<tr>
|
||
|
<td align="center" valign="top"> </td>
|
||
|
<td align="center" valign="top"> </td>
|
||
|
<td align="left" valign="top">CHAR(*)</td>
|
||
|
<td align="left" valign="top">Label information</td>
|
||
|
</tr>
|
||
|
</table>
|
||
|
|
||
|
<br>
|
||
|
<br>
|
||
|
|
||
|
|
||
|
<h3><a name="CTGINFO">Label information</a></h3>
|
||
|
|
||
|
<p>The label information. Each label information entry has the following
|
||
|
format. For more details about the fields in the following table, see <a href=
|
||
|
"#HDRFLDXX">Field Descriptions</a>.</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%">CHAR(80)</td>
|
||
|
<td align="left" valign="top" width="60%">Label 1</td>
|
||
|
</tr>
|
||
|
|
||
|
<tr>
|
||
|
<td align="center" valign="top" width="10%">80</td>
|
||
|
<td align="center" valign="top" width="10%">50</td>
|
||
|
<td align="left" valign="top" width="20%">CHAR(80)</td>
|
||
|
<td align="left" valign="top" width="60%">Label 2</td>
|
||
|
</tr>
|
||
|
|
||
|
<tr>
|
||
|
<td align="center" valign="top" width="10%">160</td>
|
||
|
<td align="center" valign="top" width="10%">A0</td>
|
||
|
<td align="left" valign="top" width="20%">CHAR(32)</td>
|
||
|
<td align="left" valign="top" width="60%">Logical block ID</td>
|
||
|
</tr>
|
||
|
|
||
|
<tr>
|
||
|
<td align="center" valign="top" width="10%">192</td>
|
||
|
<td align="center" valign="top" width="10%">C0</td>
|
||
|
<td align="left" valign="top" width="20%">CHAR(10)</td>
|
||
|
<td align="left" valign="top" width="60%">Sequence number</td>
|
||
|
</tr>
|
||
|
|
||
|
<tr>
|
||
|
<td align="center" valign="top" width="10%">202</td>
|
||
|
<td align="center" valign="top" width="10%">CA</td>
|
||
|
<td align="left" valign="top" width="20%">CHAR(10)</td>
|
||
|
<td align="left" valign="top" width="60%">Multi-volume sequence number</td>
|
||
|
</tr>
|
||
|
|
||
|
<tr>
|
||
|
<td align="center" valign="top" width="10%">212</td>
|
||
|
<td align="center" valign="top" width="10%">D4</td>
|
||
|
<td align="left" valign="top" width="20%">CHAR(8)</td>
|
||
|
<td align="left" valign="top" width="60%">S/36 File type</td>
|
||
|
</tr>
|
||
|
</table>
|
||
|
|
||
|
<br>
|
||
|
<br>
|
||
|
|
||
|
<p>For more information regarding IBM Standard Volume Labels and Data Set Labels 1 and 2, select the appropriate topic below:</p>
|
||
|
<ul>
|
||
|
<li><a href="../rzatb/vdefn.htm">IBM Standard Volume Label (VOL1)</a></li>
|
||
|
<li><a href="../rzatb/hdr1d.htm">IBM Standard Data Set Label 1 (HDR1/EOV1/EOF1)</a></li>
|
||
|
<li><a href="../rzatb/hdr2d.htm">IBM Standard Data Set Label 2 (HDR2/EOV2/EOF2)</a></li>
|
||
|
</ul>
|
||
|
|
||
|
<h3><a name="HDRFLDXX">Field Descriptions</a></h3>
|
||
|
|
||
|
<p><strong>Additional label entries.</strong> Indicates if there were labels on
|
||
|
tape that were not returned because the return data would have exceeded
|
||
|
16,000,000 Bytes. The following values can be returned:</p>
|
||
|
|
||
|
<table cellpadding="5">
|
||
|
<!-- cols="5 95" -->
|
||
|
<tr>
|
||
|
<td align="left" valign="top"><em>0</em></td>
|
||
|
<td align="left" valign="top">No additional label entries.</td>
|
||
|
</tr>
|
||
|
|
||
|
<tr>
|
||
|
<td align="left" valign="top"><em>1</em></td>
|
||
|
<td align="left" valign="top">There were more label entries to return.</td>
|
||
|
</tr>
|
||
|
</table>
|
||
|
|
||
|
<p><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>
|
||
|
|
||
|
<p><strong>Bytes returned.</strong> The number of bytes of data returned.</p>
|
||
|
|
||
|
<p><strong>Cartridge ID.</strong> The cartridge identifier for the media. This
|
||
|
field will be blanks if the device is not a tape library device.</p>
|
||
|
|
||
|
<p><strong>Code.</strong> The encoding used for the data on tape. The following
|
||
|
values can be returned:</p>
|
||
|
|
||
|
<table cellpadding="5">
|
||
|
<!-- cols="5 95" -->
|
||
|
<tr>
|
||
|
<td align="left" valign="top"><em>0</em></td>
|
||
|
<td align="left" valign="top">ASCII encoding is used.</td>
|
||
|
</tr>
|
||
|
|
||
|
<tr>
|
||
|
<td align="left" valign="top"><em>1</em></td>
|
||
|
<td align="left" valign="top">EBCDIC encoding is used.</td>
|
||
|
</tr>
|
||
|
|
||
|
<tr>
|
||
|
<td align="left" valign="top"><em>blank</em></td>
|
||
|
<td align="left" valign="top">Non-labeled tape.</td>
|
||
|
</tr>
|
||
|
</table>
|
||
|
|
||
|
<p><strong>Density.</strong> The density that is used for the data on the
|
||
|
tape.</p>
|
||
|
|
||
|
<p><strong>Device name.</strong> The tape device or tape library device that
|
||
|
was used.</p>
|
||
|
|
||
|
<p><strong>Ending file sequence number.</strong> The ending sequence number for
|
||
|
which the labels are to be retrieved. When a numeric value is specified it must
|
||
|
be left justified and padded with blanks on the right. The ending sequence
|
||
|
number can not be less than the starting file sequence number. The following
|
||
|
special values are supported:</p>
|
||
|
|
||
|
<table cellpadding="5">
|
||
|
<!-- cols="15 85" -->
|
||
|
<tr>
|
||
|
<td align="left" valign="top"><em>*ONLY</em></td>
|
||
|
<td align="left" valign="top">Only the file specified by the starting file
|
||
|
sequence number will be retrieved, if it matches the specified file label.
|
||
|
<strong>This is the default value.</strong></td>
|
||
|
</tr>
|
||
|
|
||
|
<tr>
|
||
|
<td align="left" valign="top"><em>*LAST</em></td>
|
||
|
<td align="left" valign="top">The labels on tape that match the specifed file
|
||
|
label are to be retrieved, starting with the file specified by the Starting
|
||
|
file sequence number and ending with the last file sequence number on
|
||
|
tape.</td>
|
||
|
</tr>
|
||
|
|
||
|
<tr>
|
||
|
<td align="left" valign="top"><em>blank</em></td>
|
||
|
<td align="left" valign="top">The ending file sequence number will not be used.
|
||
|
This value is only valid when the special value *ALL is specified for the
|
||
|
starting file sequence number.</td>
|
||
|
</tr>
|
||
|
</table>
|
||
|
|
||
|
<p><strong>End option.</strong> The operation to perform on the tape volume
|
||
|
after the retrieve completes. The following special values are supported:</p>
|
||
|
|
||
|
<table cellpadding="5">
|
||
|
<!-- cols="5 95" -->
|
||
|
<tr>
|
||
|
<td align="left" valign="top"><em>0</em></td>
|
||
|
<td align="left" valign="top">Rewind the tape. <strong>This is the default
|
||
|
value.</strong></td>
|
||
|
</tr>
|
||
|
|
||
|
<tr>
|
||
|
<td align="left" valign="top"><em>1</em></td>
|
||
|
<td align="left" valign="top">Rewind and unload the tape.</td>
|
||
|
</tr>
|
||
|
<tr>
|
||
|
<td align="left" valign="top"><em>2</em></td>
|
||
|
<td align="left" valign="top">Leave the tape at the current position.</td>
|
||
|
</tr>
|
||
|
</table>
|
||
|
|
||
|
<p><strong>Label 1.</strong> The contents of the first trailer label for the
|
||
|
file sequence.</p>
|
||
|
|
||
|
<p><strong>Label 2.</strong> The contents of the second trailer label for the
|
||
|
file sequence.</p>
|
||
|
|
||
|
<p><strong>Leading tape mark.</strong> Indicates if the tape was a leading tape
|
||
|
mark tape. The following values can be returned:</p>
|
||
|
|
||
|
<table cellpadding="5">
|
||
|
<!-- cols="5 95" -->
|
||
|
<tr>
|
||
|
<td align="left" valign="top"><em>0</em></td>
|
||
|
<td align="left" valign="top">Not a leading tape mark tape.</td>
|
||
|
</tr>
|
||
|
|
||
|
<tr>
|
||
|
<td align="left" valign="top"><em>1</em></td>
|
||
|
<td align="left" valign="top">Leading tape mark tape.</td>
|
||
|
</tr>
|
||
|
</table>
|
||
|
|
||
|
<p><strong>Length of label information entry.</strong> When label information
|
||
|
is available this field is set to the length, in bytes, of a single label
|
||
|
information entry. A value of zero is returned if the tape is not a standard
|
||
|
labeled tape, if there are no labels on the tape, or if the receiver variable
|
||
|
is not large enough to hold any label information entries.</p>
|
||
|
|
||
|
<p><strong>Logical block ID.</strong> The logical block identifier for the file
|
||
|
sequence.</p>
|
||
|
|
||
|
<p><strong>Multi-volume sequence number.</strong> The sequence number for the
|
||
|
tape volume.</p>
|
||
|
|
||
|
<p><strong>Number of label information entries.</strong> If there is room in
|
||
|
the receiver variable for 1 or more complete label information entries, this
|
||
|
value is set to the number of complete label information entries returned. The
|
||
|
Bytes returned value can be used to determine if any partial label information
|
||
|
entries were returned.</p>
|
||
|
|
||
|
<p>If there is room in the receiver variable for only part of the first label
|
||
|
information entry, this value is set to 1 and it will be necessary to use the
|
||
|
Bytes returned value to determine which label information fields are valid.</p>
|
||
|
|
||
|
<p>A value of zero is returned if the tape is not a standard labeled tape, if
|
||
|
there are no labels on the tape, or if the receiver variable is not large
|
||
|
enough to hold any label information entries.</p>
|
||
|
|
||
|
<p><strong> Note:</strong> A maximum of 72,726 entries can be returned.</p>
|
||
|
|
||
|
<p><strong>Offset to label information.</strong> The offset, in bytes, to the
|
||
|
label information. A value of zero is returned if the tape is not a standard
|
||
|
labeled tape, if there are no labels on the tape, or if the receiver variable
|
||
|
is not large enough to hold any label information.</p>
|
||
|
|
||
|
<p><strong>Requested file label.</strong> The data file label that is to be
|
||
|
retrieved. The data file label is a maximum of 17 characters in length and is
|
||
|
case sensitive. The following special value is supported:</p>
|
||
|
|
||
|
<table cellpadding="5">
|
||
|
<!-- cols="15 85" -->
|
||
|
<tr>
|
||
|
<td align="left" valign="top"><em>*ALL</em></td>
|
||
|
<td align="left" valign="top">All file labels within the specified sequence
|
||
|
number range are to be retrieved. <strong>This is the default
|
||
|
value.</strong></td>
|
||
|
</tr>
|
||
|
</table>
|
||
|
|
||
|
<p><strong>Note:</strong> When a specific file label is requested, the label
|
||
|
information will only be returned for the first file found that matches the
|
||
|
requested file label.</p>
|
||
|
|
||
|
<p><strong>Requested volume identifier.</strong> The tape volume for which the
|
||
|
labels are to be retrieved. For a tape library device this field should be set
|
||
|
to a cartridge identifier to be mounted and used. The following special value
|
||
|
is supported:</p>
|
||
|
|
||
|
<table cellpadding="5">
|
||
|
<!-- cols="15 85" -->
|
||
|
<tr>
|
||
|
<td align="left" valign="top"><em>blanks</em></td>
|
||
|
<td align="left" valign="top">The currently mounted tape cartridge is used.
|
||
|
<strong>This is the default value.</strong></td>
|
||
|
</tr>
|
||
|
</table>
|
||
|
|
||
|
<p><strong>Reserved.</strong> An ignored field. This field is set to
|
||
|
hexadecimal zeros for output fields and must be set to hexadecimal zeros for
|
||
|
input fields.</p>
|
||
|
|
||
|
<p><strong>S/36 File type.</strong> The System/36 file type for the file
|
||
|
sequence. The following file types can be returned:</p>
|
||
|
|
||
|
<ul>
|
||
|
<li>ARCHIVE</li>
|
||
|
|
||
|
<li>APARFILE</li>
|
||
|
|
||
|
<li>COPYFILE</li>
|
||
|
|
||
|
<li>EXCHANGE</li>
|
||
|
|
||
|
<li>LIBRFILE</li>
|
||
|
|
||
|
<li>SAVEFLDR</li>
|
||
|
|
||
|
<li>SAVELIBR</li>
|
||
|
</ul>
|
||
|
|
||
|
<br>
|
||
|
<br>
|
||
|
|
||
|
|
||
|
<p><strong>Sequence number.</strong> The file sequence number.</p>
|
||
|
|
||
|
<p><strong>Standard label.</strong> Indicates if the tape was a standard
|
||
|
labeled tape. The following values can be returned:</p>
|
||
|
|
||
|
<table cellpadding="5">
|
||
|
<!-- cols="5 95" -->
|
||
|
<tr>
|
||
|
<td align="left" valign="top"><em>0</em></td>
|
||
|
<td align="left" valign="top">Non-labeled tape.</td>
|
||
|
</tr>
|
||
|
|
||
|
<tr>
|
||
|
<td align="left" valign="top"><em>1</em></td>
|
||
|
<td align="left" valign="top">Standard labeled tape.</td>
|
||
|
</tr>
|
||
|
</table>
|
||
|
|
||
|
<p><strong>Starting file sequence number.</strong> The starting sequence number
|
||
|
for which the labels are to be retrieved. When a numeric value is specified it
|
||
|
must be left justified and padded with blanks on the right. The following
|
||
|
special values are supported:</p>
|
||
|
|
||
|
<table cellpadding="5">
|
||
|
<!-- cols="15 85" -->
|
||
|
<tr>
|
||
|
<td align="left" valign="top"><em>*ALL</em></td>
|
||
|
<td align="left" valign="top">All labels on tape are to be retrieved that match
|
||
|
the specified file label.
|
||
|
|
||
|
<p><strong>Note:</strong> When this value is used the ending file sequence
|
||
|
number must be set to blanks.</p>
|
||
|
</td>
|
||
|
</tr>
|
||
|
|
||
|
<tr>
|
||
|
<td align="left" valign="top"><em>*FIRST</em></td>
|
||
|
<td align="left" valign="top">The labels on tape that match the specified file
|
||
|
label are to be retrieved, starting with the first file label. <strong>This is
|
||
|
the default value.</strong></td>
|
||
|
</tr>
|
||
|
</table>
|
||
|
|
||
|
<p><strong>Volume label.</strong> The volume label read from the tape. This
|
||
|
field is set to blanks for a non-labeled tape. <br>
|
||
|
<br>
|
||
|
</p>
|
||
|
|
||
|
<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" width="15%">CPF24B4 E</td>
|
||
|
<td align="left" valign="top" width="85%">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">CPF3C21 E</td>
|
||
|
<td align="left" valign="top">Format name &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">CPF3C39 E</td>
|
||
|
<td align="left" valign="top">Value for reserved field not valid.</td>
|
||
|
</tr>
|
||
|
|
||
|
<tr>
|
||
|
<td align="left" valign="top">CPF3C3C E</td>
|
||
|
<td align="left" valign="top">Value for parameter &1 is not valid.</td>
|
||
|
</tr>
|
||
|
|
||
|
<tr>
|
||
|
<td align="left" valign="top">CPF3C4B E</td>
|
||
|
<td align="left" valign="top">Value not valid for field &1.</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">CPF4108 E</td>
|
||
|
<td align="left" valign="top">Media error on volume &8 device &4.</td>
|
||
|
</tr>
|
||
|
|
||
|
<tr>
|
||
|
<td align="left" valign="top">CPF4119 E</td>
|
||
|
<td align="left" valign="top">Device &4 cannot process loaded volume.</td>
|
||
|
</tr>
|
||
|
|
||
|
<tr>
|
||
|
<td align="left" valign="top">CPF4120 E</td>
|
||
|
<td align="left" valign="top">Device &4 or an attached gateway device reported a hardware failure.</td>
|
||
|
</tr>
|
||
|
|
||
|
<tr>
|
||
|
<td align="left" valign="top">CPF4121 E</td>
|
||
|
<td align="left" valign="top">Interface error while using device &4.</td>
|
||
|
</tr>
|
||
|
|
||
|
<tr>
|
||
|
<td align="left" valign="top">CPF412C E</td>
|
||
|
<td align="left" valign="top">Cartridge &6 not found.</td>
|
||
|
</tr>
|
||
|
|
||
|
<tr>
|
||
|
<td align="left" valign="top">CPF412D E</td>
|
||
|
<td align="left" valign="top">Cartridge not available.</td>
|
||
|
</tr>
|
||
|
|
||
|
<tr>
|
||
|
<td align="left" valign="top">CPF412F E</td>
|
||
|
<td align="left" valign="top">Cartridge &6 not available.</td>
|
||
|
</tr>
|
||
|
|
||
|
<tr>
|
||
|
<td align="left" valign="top">CPF414C E</td>
|
||
|
<td align="left" valign="top">Command not allowed.</td>
|
||
|
</tr>
|
||
|
|
||
|
<tr>
|
||
|
<td align="left" valign="top">CPF414E E</td>
|
||
|
<td align="left" valign="top">Library device &5 not ready.</td>
|
||
|
</tr>
|
||
|
|
||
|
<tr>
|
||
|
<td align="left" valign="top">CPF414F E</td>
|
||
|
<td align="left" valign="top">Library device storage slots full.</td>
|
||
|
</tr>
|
||
|
|
||
|
<tr>
|
||
|
<td align="left" valign="top">CPF415A E</td>
|
||
|
<td align="left" valign="top">*MOUNTED not correct.</td>
|
||
|
</tr>
|
||
|
|
||
|
<tr>
|
||
|
<td align="left" valign="top">CPF415E E</td>
|
||
|
<td align="left" valign="top">Resource request timed out on device &4.</td>
|
||
|
</tr>
|
||
|
|
||
|
<tr>
|
||
|
<td align="left" valign="top">CPF416A E</td>
|
||
|
<td align="left" valign="top">No device available.</td>
|
||
|
</tr>
|
||
|
|
||
|
<tr>
|
||
|
<td align="left" valign="top"><img src="delta.gif" alt="Start of change">
|
||
|
CPF41B3 E</td>
|
||
|
<td align="left" valign="top">No more volumes to mount from catalog.<img src="deltaend.gif" alt="End of change"></td>
|
||
|
</tr>
|
||
|
|
||
|
<tr>
|
||
|
<td align="left" valign="top"><img src="delta.gif" alt="Start of change">
|
||
|
CPF41B4 E</td>
|
||
|
<td align="left" valign="top">Virtual tape volume not available.<img src="deltaend.gif" alt="End of change"></td>
|
||
|
</tr>
|
||
|
|
||
|
<tr>
|
||
|
<td align="left" valign="top"><img src="delta.gif" alt="Start of change">
|
||
|
CPF41B5 E</td>
|
||
|
<td align="left" valign="top">Virtual tape volume not found.<img src="deltaend.gif" alt="End of change"></td>
|
||
|
</tr>
|
||
|
|
||
|
<tr>
|
||
|
<td align="left" valign="top">CPF6708 E</td>
|
||
|
<td align="left" valign="top">Command ended due to error.</td>
|
||
|
</tr>
|
||
|
|
||
|
<tr>
|
||
|
<td align="left" valign="top">CPF6718 E</td>
|
||
|
<td align="left" valign="top">Cannot allocate device &1.</td>
|
||
|
</tr>
|
||
|
|
||
|
<tr>
|
||
|
<td align="left" valign="top">CPF6720 E</td>
|
||
|
<td align="left" valign="top">Incorrect volume &2 found on device
|
||
|
&1.</td>
|
||
|
</tr>
|
||
|
|
||
|
<tr>
|
||
|
<td align="left" valign="top">CPF6721 E</td>
|
||
|
<td align="left" valign="top">Device &1 not a tape device.</td>
|
||
|
</tr>
|
||
|
|
||
|
<tr>
|
||
|
<td align="left" valign="top">CPF6723 E</td>
|
||
|
<td align="left" valign="top">File not found on volume &2 on device
|
||
|
&1.</td>
|
||
|
</tr>
|
||
|
|
||
|
<tr>
|
||
|
<td align="left" valign="top">CPF6724 E</td>
|
||
|
<td align="left" valign="top">File label &5 not found on volume
|
||
|
&2.</td>
|
||
|
</tr>
|
||
|
|
||
|
<tr>
|
||
|
<td align="left" valign="top">CPF6725 E</td>
|
||
|
<td align="left" valign="top">Ending file sequence number less than starting
|
||
|
sequence number.</td>
|
||
|
</tr>
|
||
|
|
||
|
<tr>
|
||
|
<td align="left" valign="top">CPF673A E</td>
|
||
|
<td align="left" valign="top">Device &3 not varied on.</td>
|
||
|
</tr>
|
||
|
|
||
|
<tr>
|
||
|
<td align="left" valign="top">CPF6751 E</td>
|
||
|
<td align="left" valign="top">Load failure occurred on device &4.</td>
|
||
|
</tr>
|
||
|
|
||
|
<tr>
|
||
|
<td align="left" valign="top">CPF6760 E</td>
|
||
|
<td align="left" valign="top">Device &1 not ready.</td>
|
||
|
</tr>
|
||
|
|
||
|
<tr>
|
||
|
<td align="left" valign="top">CPF6772 E</td>
|
||
|
<td align="left" valign="top">Volume on device &1 cannot be processed.</td>
|
||
|
</tr>
|
||
|
|
||
|
<tr>
|
||
|
<td align="left" valign="top">CPF67E6 E</td>
|
||
|
<td align="left" valign="top">Volume &2 not correct.</td>
|
||
|
</tr>
|
||
|
|
||
|
<tr>
|
||
|
<td align="left" valign="top">CPF9802 E</td>
|
||
|
<td align="left" valign="top">Not authorized to object &2 in &3.</td>
|
||
|
</tr>
|
||
|
|
||
|
<tr>
|
||
|
<td align="left" valign="top">CPF9814 E</td>
|
||
|
<td align="left" valign="top">Device &1 not found.</td>
|
||
|
</tr>
|
||
|
|
||
|
<tr>
|
||
|
<td align="left" valign="top">CPF9872 E</td>
|
||
|
<td align="left" valign="top">Program or service program &1 in library
|
||
|
&2 ended. Reason code &3.</td>
|
||
|
</tr>
|
||
|
</table>
|
||
|
|
||
|
<br>
|
||
|
<hr>
|
||
|
API introduced: V5R3
|
||
|
|
||
|
<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=
|
||
|
"back1.htm">Backup and Recovery APIs</a> | <a href="aplist.htm">APIs by
|
||
|
category</a></td>
|
||
|
</tr>
|
||
|
</table>
|
||
|
</body>
|
||
|
</html>
|
||
|
|