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

513 lines
14 KiB
HTML
Raw Normal View History

2024-04-02 14:02:31 +00:00
<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8">
<meta name="Copyright" content="Copyright (c) 2006 by IBM Corporation">
<title>Retrieve Job Media Library Attributes (QTARJMA) 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. -->
<!-- BACKMST SCRIPT A converted by B2H R4.1 (346) (CMS) by v2kea304 at -->
<!-- RCHVMW2 on 26 April 1999 at 10:21:58 -->
<!-- Change History: -->
<!-- YYMMDD USERID Change description -->
<!-- File cleanup completed Jan 2002 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 Job Media Library Attributes (QTARJMA) 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">Qualified job name</td>
<td align="left" valign="top">Input</td>
<td align="left" valign="top">Char(26)</td>
</tr>
<tr>
<td align="center" valign="top">5</td>
<td align="left" valign="top">Internal job identifier</td>
<td align="left" valign="top">Input</td>
<td align="left" valign="top">Char(16)</td>
</tr>
<tr>
<td align="center" valign="top">6</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 Job Media Library Attributes (QTARJMA) API retrieves the
specified job's current settings for the media library attributes. For more
information, see <a href="../rzam4/rzam4tape.htm">Tape</a> information in the
Storage Solutions topic.</p>
<br>
<h3>Authorities and Locks</h3>
<dl>
<dt><em>Job Authority</em></dt>
<dd>*JOBCTL, if the job for which information is retrieved has a different user
profile from that of the job that calls the QTARJMA API.</dd>
</dl>
<br>
<h3>Required Parameter Group</h3>
<dl>
<dt><strong>Receiver variable</strong></dt>
<dd>OUTPUT; CHAR(*)
<p>The variable that is to receive the information requested. You can specify
the size of an area smaller than the format requested as long as you specify
the receiver length parameter correctly. As a result, the API returns only the
data 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. The length must be at least 8 bytes. If
the variable is not long enough to hold the information, the data is truncated.
If the length is larger than the size of the receiver variable, the results are
not predictable.</p>
</dd>
<dt><strong>Format name</strong></dt>
<dd>INPUT; CHAR(8)
<p>The format name RJMA0100 is the only valid format name used by this API. For
more information, see <a href="#HDRRJMA1">RJMA0100 Format</a>.</p>
</dd>
<dt><strong>Qualified job name</strong></dt>
<dd>INPUT; CHAR(26)
<p>The name of the job for which information is to be returned. The qualified
job name has three parts:</p>
<dl>
<dt><em>Job name</em></dt>
<dd>CHAR(10). A specific job name or the following
special value:
<br><br>
<dl>
<dt><em>*</em></dt>
<dd>The job that this program is running in. The rest
of the qualified job name parameter must be blank.<br><br></dd>
<dt><em>*INT</em></dt>
<dd>The internal job identifier locates the job. The
user name and job number must be blank.<br><br></dd>
</dl>
</dd>
<dt><em>User name</em></dt>
<dd>CHAR(10). A specific user profile name, or blanks
when the job name is a special value or *INT.<br><br></dd>
<dt><em>Job number</em></dt>
<dd>CHAR(6). A specific job number, or blanks when
the job name specified is a special value or *INT.<br><br></dd>
</dl>
</dd>
<dt><strong>Internal job identifier</strong></dt>
<dd>INPUT; CHAR(16)
<p>The internal identifier for the job. The List Job (QUSLJOB) API creates this
identifier. If you do not specify *INT for the job name parameter, this
parameter must contain blanks. With this parameter, the system can locate the
job more quickly than with a job name.</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="HDRRJMA1">RJMA0100 Format</a></h3>
<p>The following table lists the fields for the receiver variable in the
RJMA0100 format. For more information about each field, see
<a href="#HDRRJMAFD">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">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">Offset to list of device entries</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">Number of device entries</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">Length of a device entry</td>
</tr>
<tr>
<td align="center" valign="top">20</td>
<td align="center" valign="top">14</td>
<td align="left" valign="top">CHAR(12)</td>
<td align="left" valign="top">Reserved</td>
</tr>
<tr>
<td align="left" valign="top" colspan="2" rowspan="6">Offsets vary. These
fields repeat in the order listed, for each media library device that has
attributes defined.</td>
<td align="left" valign="top">CHAR(10)</td>
<td align="left" valign="top">Media library device</td>
</tr>
<tr>
<td align="left" valign="top">CHAR(6)</td>
<td align="left" valign="top">Reserved</td>
</tr>
<tr>
<td align="left" valign="top">BINARY(4)</td>
<td align="left" valign="top">Resource allocation priority</td>
</tr>
<tr>
<td align="left" valign="top">BINARY(4)</td>
<td align="left" valign="top">Wait time for initial mount</td>
</tr>
<tr>
<td align="left" valign="top">BINARY(4)</td>
<td align="left" valign="top">Wait time for end of volume mount</td>
</tr>
<tr>
<td align="left" valign="top">CHAR(4)</td>
<td align="left" valign="top">Reserved</td>
</tr>
</table>
<br>
<br>
<h3><a name="HDRRJMAFD">Field Descriptions</a></h3>
<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>Length of a device entry.</strong> The length, in bytes, of a device
entry. A value of zero is returned if the list is empty.</p>
<p><strong>Media library device.</strong> The name of the media library device
that the attributes apply to. The special value supported is:</p>
<table cellpadding="5">
<!-- cols="15 85" -->
<tr>
<td align="left" valign="top"><em>*DEFAULT</em></td>
<td align="left" valign="top">The attributes apply to all media libraries that
do not have attributes defined.</td>
</tr>
</table>
<p><strong>Number of device entries.</strong> The number of entries in the
device list returned for this format. A value of zero is returned if the list
is empty.</p>
<p><strong>Offset to the list of device entries.</strong> The offset, in bytes,
to the list of device entries returned with this format. A value of zero is
returned if the list is empty.</p>
<p><strong>Reserved.</strong> All reserved fields will contain hexadecimal
zeros.</p>
<p><strong>Resource allocation priority.</strong> The priority that the
specified job will be given when the job requests a tape resource within a
media library device.</p>
<p><em>Exceptions:</em></p>
<ul>
<li>Value of -2 implies *DEV. The priority specified in the device description
will be used when the job requests a tape resource.</li>
<li>Value of -31 implies *JOB. The specified job's run-time priority will be
used for the resource allocation priority when the job requests a tape
resource.</li>
</ul>
<p><strong>Wait time for end of volume mount.</strong> The maximum amount of
time, in minutes, a request will wait for the allocation of a tape resource to
mount the next volume after the end of volume is reached.</p>
<p><em>Exceptions:</em></p>
<ul>
<li>Value of -2 implies *DEV. The end of volume mount wait time specified in
the device description will be used.</li>
<li>Value of -8 implies *NOMAX. The specified job will wait until a resource
becomes available.</li>
<li>Value of -31 implies *JOB. The specified job's default wait time will be
used to calculate the wait time. The time is calculated by rounding the default
wait time, in seconds, to the next highest minute.</li>
<li>Value of -32 implies *IMMED. The specified job will not wait for a resource
to become available.</li>
</ul>
<p><strong>Wait time for initial mount.</strong> The maximum amount of time, in
minutes, a request will wait for the allocation of a tape resource to mount the
first volume.</p>
<p><em>Exceptions:</em></p>
<ul>
<li>Value of -2 implies *DEV. The initial mount wait time specified in the
device description will be used.</li>
<li>Value of -8 implies *NOMAX. The specified job will wait until a resource
becomes available.</li>
<li>Value of -31 implies *JOB. The specified job's default wait time will be
used to calculate the wait time. The time is calculated by rounding the default
wait time, in seconds, to the next highest minute.</li>
<li>Value of -32 implies *IMMED. The specified job will not wait for a resource
to become available.</li>
</ul>
<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%">CPF1343 E</td>
<td align="left" valign="top" width="85%">Job &amp;3/&amp;2/&amp;1 not valid
job type for function.</td>
</tr>
<tr>
<td align="left" valign="top">CPF136A E</td>
<td align="left" valign="top">Job &amp;3/&amp;2/&amp;1 not active.</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">CPF3C21 E</td>
<td align="left" valign="top">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">CPF3C51 E</td>
<td align="left" valign="top">Internal job identifier not valid.</td>
</tr>
<tr>
<td align="left" valign="top">CPF3C52 E</td>
<td align="left" valign="top">Internal job identifier no longer valid.</td>
</tr>
<tr>
<td align="left" valign="top">CPF3C53 E</td>
<td align="left" valign="top">Job &amp;3/&amp;2/&amp;1 not found.</td>
</tr>
<tr>
<td align="left" valign="top">CPF3C54 E</td>
<td align="left" valign="top">Job &amp;3/&amp;2/&amp;1 currently not
available.</td>
</tr>
<tr>
<td align="left" valign="top">CPF3C55 E</td>
<td align="left" valign="top">Job &amp;3/&amp;2/&amp;1 does not exist.</td>
</tr>
<tr>
<td align="left" valign="top">CPF3C58 E</td>
<td align="left" valign="top">Job name specified is not valid.</td>
</tr>
<tr>
<td align="left" valign="top">CPF3C59 E</td>
<td align="left" valign="top">Internal identifier is not blanks and job name is
not *INT.</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">CPF6708 E</td>
<td align="left" valign="top">Command ended due to error.</td>
</tr>
<tr>
<td align="left" valign="top">CPF67B6 E</td>
<td align="left" valign="top">&amp;3/&amp;2/&amp;1 not authorized to do
requested operation.</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: V4R3
<hr>
<center>
<table 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>
</center>
</body>
</html>