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

663 lines
19 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>Move Library to ASP (QHSMMOVL) 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. -->
<!-- QHSMMOVL SCRIPT A converted by B2H R4.1 (346) (CMS) by PMHALL at -->
<!-- RCHVMW2 on 7 Oct 1998 at 1:59:03 -->
<!-- File cleanup completed Feb 2002 by v2cdijab -->
<!-- Change history - the revision tagging used for changes relating to
DCR 98416 is v5r2delta LAW -->
<!-- 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 language="Javascript" src="../rzahg/synch.js" type="text/javascript">
</script>
<h2>Move Library to ASP (QHSMMOVL) 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%">Library 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">Target auxiliary storage pool (ASP) number</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">Check dependencies</td>
<td align="left" valign="top">Input</td>
<td align="left" valign="top">Char(10)</td>
</tr>
<tr>
<td align="center" valign="top">4</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;Optional Parameter Group 1:<br>
<!-- iddvc RMBR -->
<br>
<table width="100%">
<tr>
<td align="center" valign="top" width="10%">5</td>
<td align="left" valign="top" width="50%">Target auxiliary storage pool (ASP)
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">6</td>
<td align="left" valign="top">Source auxiliary storage pool (ASP) number</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">Source auxiliary storage pool (ASP) device
name</td>
<td align="left" valign="top">Input</td>
<td align="left" valign="top">Char(10)</td>
</tr>
</table>
<br>
&nbsp;&nbsp;Default Public Authority: *USE<br>
<!-- iddvc RMBR -->
<br>
&nbsp;&nbsp;Threadsafe: No<br>
<!-- iddvc RMBR -->
<br>
</div>
<p>The Move Library to ASP (QHSMMOVL) API moves a library and its contents from
its existing auxiliary storage pool (ASP) to the specified target ASP through a
save and restore operation. The API preserves private authorities
to the objects that would normally be lost with a save and restore operation.</p>
<p>Program (*PGM) objects in the library will be placed in library QRPLOBJ (or
library QRPLxxxxx if the library is in a primary or secondary ASP (where 'xxxxx'
is the ASP number of the primary ASP of the ASP group)) and a copy of each
*PGM object will be moved with the library to the target ASP.</p>
<p>After a library has been moved, the following attributes are changed
for every object in the library and the library.</p>
<ul>
<li>The date last used will be set to blank.</li>
<li>The change date and time will be set to the current date and time.</li>
<li>The days used count will be set to zero.</li>
<li>The date use count reset will be set to blank.</li>
<li>The restore date and time will be set to the current date and time.</li>
</ul>
<br>
<h3>Restrictions</h3>
<ul>
<li>Data queue entries are not moved and will be lost.</li>
<li>The QSYSWRK subsystem must be active.</li>
<li>A library cannot be moved in the following cases:
<ul>
<li>The library is considered a system
library. The restricted libraries are:
<ul>
<li>Any library with a name that begins with the letter 'Q'.</li>
<li>Any library with a name that begins with the symbol '#' that is not considered a
user library and the target ASP is not a basic user ASP.</li>
<li>Library SYSIBM.</li>
<li>Library SYSIBxxxxx (where xxxxx is the number of a primary ASP).</li>
</ul>
</li>
<li>The library cannot be renamed. See the RNMOBJ (Rename Object)
<a href="../rbam6/rbam6clmain.htm">Control Language (CL)</a> information in the
iSeries Information Center for the restrictions on renaming a library.</li>
<li>The library contains *JRN
or *JRNRCV objects or objects that are journaled.
</li>
<li>The library contains files with database dependencies outside the library.</li>
<li>The library is in the library list of the current thread.</li>
<li>The library is in the library list of any primary thread that is active
on the system when the QLIBLCKLVL system value is set to lock libraries
in the library list.</li>
<li>The library contains an allocated job queue or output queue.</li>
<li>The target ASP does not have enough space for the library and its objects.</li>
<li>The target ASP is not either the system ASP (ASP 1), a library-type or
empty basic user ASP (ASPs 2-32), or a primary or secondary ASP (ASPs 33-255).</li>
<li>When the target ASP is a
primary or secondary ASP, the library must contain only object types that can reside
in an ASP. For a list of supported and unsupported object types in a primary
or secondary ASP see
the <a href="../rzaly/rzalyoverview.htm">Independent disk pools</a> topic.
</li>
</ul>
</ul>
<h3>Authorities and Locks</h3>
<dl>
<dt><em>Auxiliary
Storage Pool (ASP) Device Authority</em></dt>
<dd>*USE authority for each auxiliary storage pool (ASP) device
in the ASP groupwhen
a specific ASP device name is specified for the source or target
auxiliary storage pool (ASP) device name or when a value greater than
32 is specified for the source or target auxiliary storage pool (ASP)
number.<br>
<br>
</dd>
<dt><em>Object Authority</em></dt>
<dd>See Authority Required for Objects Used by Commands in the
<a href="../books/sc415302.pdf" target="_blank">iSeries Security Reference</a>
<img src="wbpdf.gif" alt="Link to PDF"> book for detailed information on object
authorities required when you save objects.<br>
<br>
</dd>
<dt><em>Library Authority</em></dt>
<dd>*OBJALTER<br>
<br>
</dd>
<dt><em>Object Lock</em></dt>
<dd>
See the <a href="../rzaiu/rzaiuintro.htm" target="_blank">Back up your server</a>
topic for detailed information on locks that are
applied to objects during save operations.<br>
<br>
</dd>
<dt><em>Library Lock
</em></dt>
<dd>*EXCL<br>
<br>
</dd>
<dd>To prevent access to other jobs, the library is renamed to QHSMLIBxxx where
xxx is a numeric increment to allow multiple concurrent move operations.</dd>
</dl>
<br>
<br>
<h3>Required Parameter Group</h3>
<dl>
<dt><strong>Library name</strong></dt>
<dd>INPUT; CHAR(10)
<p>The name of the library to be moved to the specified auxiliary storage pool
(ASP).</p>
</dd>
<dt><strong>Target auxiliary
storage pool (ASP) number</strong></dt>
<dd>INPUT; BINARY(4)
<p>The number of the auxiliary storage pool (ASP) to which the library is to be
moved. The following values can be used for the ASP number:</p>
<table cellpadding="5">
<!-- cols="15 85" -->
<tr>
<td align="left" valign="top" nowrap><em>1-255</em></td>
<td align="left" valign="top">The number that was assigned to the ASP at
creation time. ASP 1 is the system ASP. ASP numbers 2-32 are basic user ASPs.
ASP numbers 33-255 are primary or secondary ASPs. This ASP must be different
from the ASP where the library exists.</td>
</tr>
<tr>
<td align="left" valign="top"><em>-1</em></td>
<td align="left" valign="top">The ASP value is determined from the target
auxiliary storage pool (ASP) device name parameter.</td>
</tr>
</table>
<br>
</dd>
<dt><strong>Check dependencies</strong></dt>
<dd>INPUT; CHAR(10)
<p>
Identifies whether object and journal dependencies
should be checked and whether the API is to return after the
dependency checking. When object dependencies are checked, the
API validates that every object type in the library can exist in
the target ASP. When journal dependencies are checked, the API
validates that there are no *JRN or *JRNRCV objects and no journaled
objects in the library. Database dependencies are always checked
to validate that there are no database dependencies outside the library.
You can use one of the following values:</p>
<table cellpadding="5">
<!-- cols="15 85" -->
<tr>
<td align="left" valign="top"><em>*YES</em></td>
<td align="left" valign="top">The API will check for object dependencies,
database dependencies outside the library, and for journal dependencies. An
exception is signaled in case any of the conditions are found.</td>
</tr>
<tr>
<td align="left" valign="top"><em>*NO</em></td>
<td align="left" valign="top">
The API bypasses the validation for object and journal dependencies. The
database dependencies outside of the library are checked.
This value could be used
to save on processing time if the user knows that dependencies do not exist.
However, the API will end abnormally during the move operation if dependency
conditions are encountered.</td>
</tr>
<tr>
<td align="left" valign="top"><em>*VALIDATE</em></td>
<td align="left" valign="top">
The same validation is done as when "*YES" is specified. The library is not
moved to the target ASP. Completion message
CPCB79F will be sent to the
caller of the API indicating that the library can be moved to the selected ASP.
This option is best used for planning purposes to determine which libraries
can be moved to a specific ASP.</td>
</tr>
</table>
<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>Optional Parameter Group
1</h3>
<dl>
<dt><strong>Target auxiliary storage pool (ASP) device name</strong></dt>
<dd>INPUT; CHAR(10)
<p>The name of the auxiliary storage pool (ASP) device from which storage is
allocated for the library after the move. The ASP device must have a status of
'Available'. If this parameter is omitted, the target auxiliary storage pool
(ASP) number parameter will be used. This parameter must be *TGTASP if
specified when the target auxiliary storage pool (ASP) number parameter has a
value other than -1. The target ASP device must be different from the ASP
device where the library currently exists.</p>
<p>One of the following special values may be specified:</p>
<table cellpadding="5">
<!-- cols="15 85" -->
<tr>
<td align="left" valign="top"><em>*TGTASP</em></td>
<td align="left" valign="top">The ASP is determined from the target auxiliary
storage pool (ASP) number parameter.</td>
</tr>
<tr>
<td align="left" valign="top"><em>*CURGRPPRI</em></td>
<td align="left" valign="top">If the current thread has an ASP group, the
storage for the library is allocated from the the primary ASP of the group.</td>
</tr>
<tr>
<td align="left" valign="top"><em>*SYSTEM</em></td>
<td align="left" valign="top">The system ASP (ASP 1).</td>
</tr>
</table>
<br>
</dd>
<dt><strong>Source auxiliary storage pool (ASP) number</strong></dt>
<dd>INPUT; BINARY(4)
<p>The number of the auxiliary storage pool (ASP) from which the library is to
be moved. If this parameter and the source auxiliary storage pool (ASP) device
name parameter are both omitted, the library name space for the current
thread will be searched for the library.</p>
<p>The following values for the ASP number can be used:</p>
<table cellpadding="5">
<!-- cols="10 90" -->
<tr>
<td align="left" valign="top" nowrap><em>1-255</em></td>
<td align="left" valign="top">The number that was assigned to the ASP at
creation time. ASP 1 is the system ASP. ASP numbers 2-32 are basic user ASPs.
ASP numbers 33-255 are primary or secondary ASPs. The primary or secondary ASP
must have a status of 'Available'.</td>
</tr>
<tr>
<td align="left" valign="top"><em>-1</em></td>
<td align="left" valign="top">The ASP value is determined from the source
auxiliary storage pool (ASP) device name parameter.</td>
</tr>
</table>
<br>
</dd>
<dt><strong>Source auxiliary storage pool (ASP) device name</strong></dt>
<dd>INPUT; CHAR(10)
<p>The name of the auxiliary storage pool (ASP) device from which storage is
allocated for the library to be moved. The ASP device must have a status of
'Available'. This parameter must be *ASP if specified when the source auxiliary
storage pool (ASP) number parameter has a value other than -1. If this
parameter and the source auxiliary storage pool (ASP) number parameter are both
omitted, the library name space for the current thread will be searched for
the library.</p>
<p>One of the following special values may be specified:</p>
<table cellpadding="5">
<!-- cols="15 85" -->
<tr>
<td align="left" valign="top"><em>*ASP</em></td>
<td align="left" valign="top">The ASP to be searched is determined from the
source auxiliary storage pool (ASP) number parameter.</td>
</tr>
<tr>
<td align="left" valign="top"><em>*</em></td>
<td align="left" valign="top">The ASPs in the library name space for the
current thread will be searched for the library.</td>
</tr>
<tr>
<td align="left" valign="top"><em>*CURASPGRP</em></td>
<td align="left" valign="top">The ASPs in the ASP group for the current
thread will be searched for the library.</td>
</tr>
<tr>
<td align="left" valign="top"><em>*SYSBAS</em></td>
<td align="left" valign="top">The system ASP (ASP 1) and defined basic user
ASPs (ASPs 2-32) will be searched for the library.</td>
</tr>
</table>
</dd>
</dl>
<br>
<h3>Error Messages</h3>
<table 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">CPFB78A E</td>
<td align="left" valign="top">Job queue &amp;1 in library &amp;2 is attached to
subsystem &amp;3.</td>
</tr>
<tr>
<td align="left" valign="top">
CPFB78C E</td>
<td align="left" valign="top">Library &amp;1 not moved or migrated.</td>
</tr>
<tr>
<td align="left" valign="top">CPFB78D E</td>
<td align="left" valign="top">Library &amp;1 not moved or migrated.</td>
</tr>
<tr>
<td align="left" valign="top">CPFB78E E</td>
<td align="left" valign="top">Move or migrate of library &amp;1 failed.</td>
</tr>
<tr>
<td align="left" valign="top">
CPFB78F E</td>
<td align="left" valign="top">Move or migrate of library &amp;1 failed</td>
</tr>
<tr>
<td align="left" valign="top">CPFB780 E</td>
<td align="left" valign="top">Not authorized to library &amp;1.</td>
</tr>
<tr>
<td align="left" valign="top">CPFB782 E</td>
<td align="left" valign="top">Library &amp;1 cannot be moved or migrated into
an object-based ASP &amp;2.</td>
</tr>
<tr>
<td align="left" valign="top">CPFB784 E</td>
<td align="left" valign="top">Target ASP &amp;1 is not valid for the move or
migrate operation.</td>
</tr>
<tr>
<td align="left" valign="top">CPFB785 E</td>
<td align="left" valign="top">Library &amp;1 contains objects not valid for
selected ASP.</td>
</tr>
<tr>
<td align="left" valign="top">CPFB786 E</td>
<td align="left" valign="top">Insufficient disk capacity in ASP &amp;1 for
specified objects.</td>
</tr>
<tr>
<td align="left" valign="top">CPFB787 E</td>
<td align="left" valign="top">Library &amp;1 has journal dependencies.</td>
</tr>
<tr>
<td align="left" valign="top">CPFB788 E</td>
<td align="left" valign="top">Library &amp;1 has database dependencies.</td>
</tr>
<tr>
<td align="left" valign="top">CPFB789 E</td>
<td align="left" valign="top">Output queue &amp;1 in library &amp;2 is attached
to writer &amp;3.</td>
</tr>
<tr>
<td align="left" valign="top">CPFB79E E</td>
<td align="left" valign="top">Auxiliary storage pool &amp;1 does not
exist.</td>
</tr>
<tr>
<td align="left" valign="top">CPFB791 E</td>
<td align="left" valign="top">Cannot access object &amp;1 in library &amp;2
type &amp;3.</td>
</tr>
<tr>
<td align="left" valign="top">CPFB792 E</td>
<td align="left" valign="top">An error was encountered while moving or
migrating library &amp;1.</td>
</tr>
<tr>
<td align="left" valign="top">CPFB793 E</td>
<td align="left" valign="top">Move or migrate of job queue entries failed.</td>
</tr>
<tr>
<td align="left" valign="top">CPFB794 E</td>
<td align="left" valign="top">Move of output queue entries failed.</td>
</tr>
<tr>
<td align="left" valign="top">CPFB795 E</td>
<td align="left" valign="top">
Library &amp;1 cannot be allocated.</td>
</tr>
<tr>
<td align="left" valign="top">CPFB799 E</td>
<td align="left" valign="top">Unexpected condition with &amp;1 API. Reason
&amp;6.</td>
</tr>
<tr>
<td align="left" valign="top">
CPFB8ED E</td>
<td align="left" valign="top">Device description &amp;1 not correct for
operation.</td>
</tr>
<tr>
<td align="left" valign="top">CPF2115 E</td>
<td align="left" valign="top">Object &amp;1 in &amp;2 type *&amp;3
damaged.</td>
</tr>
<tr>
<td align="left" valign="top">
CPF2166 E</td>
<td align="left" valign="top">Library name &amp;1 not valid.</td>
</tr>
<tr>
<td align="left" valign="top">
CPF218C E</td>
<td align="left" valign="top">&amp;1 not a primary or secondary ASP.</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">
CPF3C36 E</td>
<td align="left" valign="top">Number of parameters, &amp;1, entered for this
API was not valid.</td>
</tr>
<tr>
<td align="left" valign="top">
CPF3C3C E</td>
<td align="left" valign="top">Value for parameter &amp;1 not valid.</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">CPF9810 E</td>
<td align="left" valign="top">Library &amp;1 not found.</td>
</tr>
<tr>
<td align="left" valign="top">
CPF9814 E</td>
<td align="left" valign="top">Device &amp;1 not found.</td>
</tr>
<tr>
<td valign="top">CPF9825 E</td>
<td valign="top">Not authorized to device &amp;1.</td>
</tr>
<tr>
<td valign="top">CPF9833 E</td>
<td valign="top">*CURASPGRP or *CURGRPPRI specified and thread has no ASP
group.</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>
<hr>
API introduced: V4R3
<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=
"obj1.htm">Object APIs</a> | <a href="aplist.htm">APIs by category</a></td>
</tr>
</table>
</body>
</html>