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

2027 lines
64 KiB
HTML
Raw 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>Restore Object (QsrRestore) 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: -->
<!-- 010514 THOMP v5r2 XPF D98457 SR support for /QOPT -->
<!-- 020601 JSIMON v5r3 XPF D99092 OBJFTR -->
<!-- 020929 JSIMON v5r3 XPF P9A17718 change OBJFTR to PATTERN -->
<!-- 030422 DRH v5r3 UHLP P9A28560 See CL help text updates -->
<!-- 040204 THOMP v5r4 XPF D99777 RST create *DIR supports -->
<!-- 040803 THOMP v5r4 XPF D99833 parallel tape support -->
<!-- 050320 THOMP v5r4 XPF D3602.1 update ALWOBJDIF() -->
<!-- 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>Restore Object (QsrRestore) API</h2>
<div class="box" style="width: 80%;">
&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%">Qualified user space name</td>
<td align="left" valign="top" width="20%">Input</td>
<td align="left" valign="top" width="20%">Char(20)</td>
</tr>
<tr>
<td align="center" valign="top">2</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;Service Program Name: QSRLIB01<br>
<!-- iddvc RMBR -->
<br>
&nbsp;&nbsp;Default Public Authority: *USE<br>
<!-- iddvc RMBR -->
<br>
&nbsp;&nbsp;Threadsafe: No<br>
<!-- iddvc RMBR -->
<br>
</div>
<p>The Restore Object (QsrRestore) API restores a copy of one or more objects
that can be used in the integrated file system.</p>
<!-- <p>For detailed restrictions on using this API to restore objects in libraries
or to restore document library objects, see the <a href=
"../books/sc415304.pdf" target="_blank">Backup and Recovery</a><img src=
"wbpdf.gif" alt="Link to PDF"> book.</p> -->
<br>
<h3>Authorities and Locks</h3>
<dl>
<dt><strong><em>User Space</em></strong></dt>
<dd>
<dl>
<dt><em>User Space Authority</em></dt>
<dd>*USE</dd>
<dt><em>User Space Library Authority</em></dt>
<dd>*EXECUTE</dd>
<dt><em>User Space Lock</em></dt>
<dd>*EXCLRD</dd>
</dl>
<br>
</dd>
<dt><strong><em>Objects to Be Restored, <img src="delta.gif" alt="Start of change">
Created Parent Directories, <img src="deltaend.gif" alt="End of change">Devices, and Output</em></strong></dt>
<dd>
<dl>
<dt><em>Locking</em></dt>
<dd>See the <a href="../books/sc415304.pdf" target="_blank">Backup and
Recovery</a><img src="wbpdf.gif" alt="Link to PDF"> book for information on
object locking for the Restore Object (RST) command.</dd>
<dt><em>Authority</em></dt>
<dd>In the <a href="../books/sc415302.pdf" target="_blank">iSeries Security Reference</a>
<img src="wbpdf.gif" alt="Link to PDF"> book, see the Appendix about
authorities required for the Restore Object (RST) command.</dd>
</dl>
</dd>
</dl>
<br>
<h3>Required Parameter Group</h3>
<dl>
<dt><strong>Qualified user space name</strong></dt>
<dd>INPUT; CHAR(20)</dd>
<dd>The user space that is to hold all the information for the restore
operation. The first 10 characters contain the user space name. The second 10
characters contain the name of the library where the user space is located. See
<a href="#HDRUSRSPC1">User space format</a> for the format of the information
in the user space.
<p>You can use the following special values for the library name. It should be
noted, however, that the library name that is actually used is not passed back
to the user. Care should be taken when you use these special values to avoid
unexpected results.</p>
<table cellpadding="5">
<!-- cols="15 85" -->
<tr>
<td align="left" valign="top"><em>*CURLIB</em></td>
<td align="left" valign="top">The job's current library is used to locate the
user space. If no library is specified as the current library for the job, the
QGPL library is used.</td>
</tr>
<tr>
<td align="left" valign="top"><em>*LIBL</em></td>
<td align="left" valign="top">The library list is used to locate the user
space.</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><a name="HDRUSRSPC1">User Space Format</a></h3>
<p>The following defines the format for the information in the user space. For
detailed descriptions of the fields in the user space format, see
<a href="#HDRUSFDS1">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%">Number of variable length
records</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">Offset to first record</td>
</tr>
<tr>
<td align="center" valign="top">8</td>
<td align="center" valign="top">8</td>
<td align="left" valign="top">CHAR(8)</td>
<td align="left" valign="top">Reserved</td>
</tr>
<tr>
<td align="left" valign="top" colspan="4"><strong>Note:</strong> These fields
repeat for each variable length record.</td>
</tr>
<tr>
<td align="center" valign="top">&nbsp;</td>
<td align="center" valign="top">&nbsp;</td>
<td align="left" valign="top">BINARY(4)</td>
<td align="left" valign="top">Key</td>
</tr>
<tr>
<td align="center" valign="top">&nbsp;</td>
<td align="center" valign="top">&nbsp;</td>
<td align="left" valign="top">BINARY(4)</td>
<td align="left" valign="top">Offset to next record</td>
</tr>
<tr>
<td align="center" valign="top">&nbsp;</td>
<td align="center" valign="top">&nbsp;</td>
<td align="left" valign="top">CHAR(8)</td>
<td align="left" valign="top">Reserved</td>
</tr>
<tr>
<td align="center" valign="top">&nbsp;</td>
<td align="center" valign="top">&nbsp;</td>
<td align="left" valign="top">CHAR(*)</td>
<td align="left" valign="top">Data</td>
</tr>
</table>
<p>If the length of the data is longer than the key identifier's data length,
the data will be truncated at the right. No message will be issued.</p>
<p>If the specified data length is shorter than the key field's defined data
length, an error message is returned for binary fields. If the field is a
character field, the data is padded with blanks and an error message will not
be returned.</p>
<p><strong>Note:</strong> This does not apply to keys that allow a list of
values to be specified. In these cases, the amount of data read is based on the
specified number of entries in the list.</p>
<p>If keys are duplicated in the user space, only the last value for a given
key is used for the restore operation.</p>
<p>Each variable length record must be 4-byte aligned. If not, unpredictable
results may occur.</p>
<br>
<h3><a name="HDRUSFDS1">Field Descriptions</a></h3>
<p><strong>Data.</strong> The data used to specify the value for the given
key.</p>
<p><strong>Key.</strong> The parameter of the Restore Object (RST) command to
specify. See <a href="#HDRKEYFLD3">Valid Keys</a> for the list of valid
keys.</p>
<p><strong>Offset to first record.</strong> The offset from the beginning of
the user space to the first variable length record.</p>
<p><strong>Offset to next record.</strong> The offset from the beginning of the
user space to the next variable length record.</p>
<p><strong>Number of variable length records.</strong> The number of variable
length records that are passed in the user space. <img src="delta.gif" alt=
"Start of change">The valid range is from 2
through 19.<img src= "deltaend.gif" alt="End of change"></p>
<p><strong>Reserved.</strong> This field should contain x'00's.</p>
<br>
<h3><a name="HDRKEYFLD3">Valid Keys</a></h3>
<p>The following table lists the valid keys for the key field area of the
variable length record. For detailed descriptions of the keys, see the
<a href="#HDRSOLDES1">Field Descriptions</a>.</p>
<p>Some messages for this API refer to parameters and values of the Restore
Object (RST) command. This table can also be used to locate the key names that
correspond to the RST command parameters. The field descriptions contain, in
addition to detailed descriptions, the corresponding parameter values.</p>
<p>The object path name key and the device path name key are required keys. The
other keys are optional.</p>
<table border width="80%">
<!-- cols="10 20 35 35" -->
<tr>
<th align="center" valign="bottom">Key</th>
<th align="left" valign="bottom">Type</th>
<th align="left" valign="bottom">Field</th>
<th align="left" valign="bottom">RST Command<br>
Parameter</th>
</tr>
<tr>
<td align="center" valign="top" width="10%">1</td>
<td align="left" valign="top" width="20%">CHAR(*)</td>
<td align="left" valign="top" width="35%">Device path name</td>
<td align="left" valign="top" width="35%">DEV</td>
</tr>
<tr>
<td align="center" valign="top">2</td>
<td align="left" valign="top">CHAR(*)</td>
<td align="left" valign="top">Object path name</td>
<td align="left" valign="top">OBJ</td>
</tr>
<tr>
<td align="center" valign="top">3</td>
<td align="left" valign="top">CHAR(1)</td>
<td align="left" valign="top">Directory subtree</td>
<td align="left" valign="top">SUBTREE</td>
</tr>
<tr>
<td align="center" valign="top">4</td>
<td align="left" valign="top">CHAR(1)</td>
<td align="left" valign="top">System</td>
<td align="left" valign="top">SYSTEM</td>
</tr>
<tr>
<td align="center" valign="top">5</td>
<td align="left" valign="top">CHAR(7)</td>
<td align="left" valign="top">Save date</td>
<td align="left" valign="top">SAVDATE</td>
</tr>
<tr>
<td align="center" valign="top">6</td>
<td align="left" valign="top">CHAR(8)</td>
<td align="left" valign="top">Save time</td>
<td align="left" valign="top">SAVTIME</td>
</tr>
<tr>
<td align="center" valign="top">7</td>
<td align="left" valign="top">CHAR(1)</td>
<td align="left" valign="top">Option</td>
<td align="left" valign="top">OPTION</td>
</tr>
<tr>
<td align="center" valign="top">8</td>
<td align="left" valign="top">CHAR(*)</td>
<td align="left" valign="top">Allow object differences</td>
<td align="left" valign="top">ALWOBJDIF</td>
</tr>
<tr>
<td align="center" valign="top">9</td>
<td align="left" valign="top">CHAR(2)</td>
<td align="left" valign="top">Force object conversion</td>
<td align="left" valign="top">FRCOBJCVN</td>
</tr>
<tr>
<td align="center" valign="top">10</td>
<td align="left" valign="top">CHAR(*)</td>
<td align="left" valign="top">Volume identifier</td>
<td align="left" valign="top">VOL</td>
</tr>
<tr>
<td align="center" valign="top">11</td>
<td align="left" valign="top">CHAR(*)</td>
<td align="left" valign="top">Label</td>
<td align="left" valign="top">LABEL</td>
</tr>
<tr>
<td align="center" valign="top">12</td>
<td align="left" valign="top">BINARY(4)</td>
<td align="left" valign="top">Sequence number</td>
<td align="left" valign="top">SEQNBR</td>
</tr>
<tr>
<td align="center" valign="top">13</td>
<td align="left" valign="top">CHAR(1)</td>
<td align="left" valign="top">End of media option</td>
<td align="left" valign="top">ENDOPT</td>
</tr>
<tr>
<td align="center" valign="top">14</td>
<td align="left" valign="top">CHAR(*)</td>
<td align="left" valign="top">Optical file</td>
<td align="left" valign="top">OPTFILE</td>
</tr>
<tr>
<td align="center" valign="top">15</td>
<td align="left" valign="top">CHAR(*)</td>
<td align="left" valign="top">Output</td>
<td align="left" valign="top">OUTPUT, INFTYPE</td>
</tr>
<tr>
<td align="center" valign="top">16</td>
<td align="left" valign="top">CHAR(*)</td>
<td align="left" valign="top">Object ID</td>
<td align="left" valign="top">OBJID</td>
</tr>
<tr>
<td align="center" valign="top">17</td>
<td align="left" valign="top">CHAR(*)</td>
<td align="left" valign="top">Name pattern</td>
<td align="left" valign="top">PATTERN</td>
</tr>
<tr>
<td align="center" valign="top"><img src="delta.gif" alt="Start of change">18</td>
<td align="left" valign="top">CHAR(1)</td>
<td align="left" valign="top">Create parent directories</td>
<td align="left" valign="top">CRTPRNDIR<img src="deltaend.gif" alt=
"End of change"></td>
</tr>
<tr>
<td align="center" valign="top"><img src="delta.gif" alt="Start of change">19</td>
<td align="left" valign="top">CHAR(10)</td>
<td align="left" valign="top">Parent directory owner</td>
<td align="left" valign="top">PRNDIROWN<img src="deltaend.gif" alt=
"End of change"></td>
</tr>
</table>
<br>
<br>
<h3><a name="HDRSOLDES1">Field Descriptions</a></h3>
<p> The values shown in parentheses are the corresponding values for the RST
command parameters.</p>
<p><strong>Allow object differences.</strong> Whether differences are allowed
between the saved object and the restored object. The differences include:</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%">&nbsp;</td>
<td align="center" valign="top" width="10%">&nbsp;</td>
<td align="left" valign="top" width="20%">BINARY(4)</td>
<td align="left" valign="top" width="60%">Number in array</td>
</tr>
<tr>
<td align="left" valign="top" colspan="4"><strong>Note:</strong> This field
repeats for each allow object difference value.</td>
</tr>
<tr>
<td align="left" valign="top">&nbsp;</td>
<td align="left" valign="top">&nbsp;</td>
<td align="left" valign="top">CHAR(1)</td>
<td align="left" valign="top">Allow object difference</td>
</tr>
</table>
<br>
<br>
<p><em>Number in array.</em> The number of allow object difference values. The
possible values are:</p>
<table cellpadding="5">
<!-- cols="10 90" -->
<tr>
<td align="left" valign="top"><em>1-3</em></td>
<td align="left" valign="top">The number of allow object difference
values.</td>
</tr>
</table>
<p><em>Allow object difference.</em> Whether differences are allowed between
the saved object and the restored object. The differences include:</p>
<img src="delta.gif" alt="Start of change">
<ul>
<li>
Authorization list: The saved object had an authorization list,
and either the object exists on the system but does not have the
same authorization list, or the object does not exist and it is
being restored to a different system than the save system.
<p><strong>Note:</strong> This key has no effect when the saved object
did not have an authorization list. If the object exists, it is restored
with the authorization list of the existing object. If it does not exist,
it is restored with no authorization list.</p></li>
<li>Ownership: The owner of an object on the system is different than the owner
of an object from the save operation.</li>
<li>Primary group: The primary group of an object on the system is different
from the primary group of an object from the save operation.</li>
</ul>
<img src="deltaend.gif" alt="End of change">
<p>The default is 0. The possible values are:<br>
<br>
<table cellpadding="5">
<!-- cols="5 95" -->
<tr>
<td align="left" valign="top"><em>0</em></td>
<td align="left" valign="top">No differences are allowed between the saved
object and the restored object. If 0 is specified for the allow object
difference field, 1 must be specified for the number in array field.
(*NONE)<br>
<img src="delta.gif" alt="Start of change">
<p>If an object already exists on the system with a different owner or
primary group than the saved object, the object is not restored.</p>
<p>If the saved object had an authorization list and the object
exists on the system but does not have the same authorization list,
the object is not restored.</p>
<p>If the saved object had an authorization list and the object
does not exist and it is being restored to a different system than
the save system, the object is restored, but it is not linked to the
authorization list, and the public authority is set to *EXCLUDE.</p>
<img src="deltaend.gif" alt="End of change"><br>
</td>
</tr>
<tr>
<td align="left" valign="top"><em>1</em></td>
<td align="left" valign="top">All differences are allowed between the saved
object and the restored object. If 1 is specified for the allow object
difference field, 1 must be specified for the number in array field.
(*ALL)<br>
<img src="delta.gif" alt="Start of change">
<p>If an object already exists on the system with a different
owner or primary group than the saved object,
the object is restored with the existing values.</p>
<p>If the saved object had an authorization list and the object
exists on the system but does not have the same authorization list,
the object is restored with the authorization list of the existing object.</p>
<p>If the saved object had an authorization list and the object
does not exist and it is being restored to a different system than
the save system, the object is restored and it is linked to the
authorization list. If the authorization list does not exist,
the public authority of the object is set to *EXCLUDE.</p>
<img src="deltaend.gif" alt="End of change"><br>
</td>
</tr>
<tr>
<td align="left" valign="top"><em>2</em></td>
<td align="left" valign="top">
<img src="delta.gif" alt="Start of change">
Authorization list differences are allowed. (*AUTL)
<p>If the saved object had an authorization list and the object
exists on the system but does not have the same authorization list,
the object is restored with the authorization list of the existing object.</p>
<p>If the saved object had an authorization list and the object
does not exist and it is being restored to a different system than
the save system, the object is restored and it is linked to the
authorization list. If the authorization list does not exist,
the public authority of the object is set to *EXCLUDE.</p>
<img src="deltaend.gif" alt="End of change"><br>
</tr>
<tr>
<td align="left" valign="top"><em>3</em></td>
<td align="left" valign="top">
Ownership differences are allowed. (*OWNER)
<p>
<img src="delta.gif" alt="Start of change">
If an object already exists on the system with a different
owner than the saved object,
the object is restored with the existing value.
<img src="deltaend.gif" alt="End of change">
</p><br>
</td>
</tr>
<tr>
<td align="left" valign="top"><em>4</em></td>
<td align="left" valign="top">Primary group differences are allowed. (*PGP)
<p>
<img src="delta.gif" alt="Start of change">
If an object already exists on the system with a different
primary group than the saved object,
the object is restored with the existing value.
<img src="deltaend.gif" alt="End of change">
</p>
</td>
</tr>
</table>
<p><img src="delta.gif" alt="Start of change"><br><strong>Create parent directories.</strong> Whether parent directories of objects being restored should be created if they do not exist. For example, if object '/a/b/c/file1' is being restored then directories '/a', '/a/b' and '/a/b/c' must exist. This key only applies to "root" (/), QOpenSys and user-defined file systems, it will be ignored for all other file systems. The default is 0. 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">Parent directories will not be created if they do not exist. Diagnostic message CPD375B will be sent and the object will not be restored. (*NO)</td>
</tr>
<tr>
<td align="left" valign="top"><em>1</em></td>
<td align="left" valign="top">The restore will create parent directories if
they do not exist. The directories created by the restore will have *EXCLUDE public
authority and will be owned by the user profile specified using
key 19 - <em>Parent directory owner</em>. (*YES)</td>
</tr>
</table>
<p><strong>Note:</strong> Other than owner, the parent directory attributes will
be set as though the Create Directory (CRTDIR) command had been used to create the
parent directory without changing any of the command defaults (the defaults are with
respect to the defaults on the shipped command and do not reflect changes that have
been made to the command default values).<img src="deltaend.gif" alt="End of change"></p>
<p><strong>Device path name.</strong> The path name of the device from which
the objects are restored.</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%">&nbsp;</td>
<td align="center" valign="top" width="10%">&nbsp;</td>
<td align="left" valign="top" width="20%">BINARY(4)</td>
<td align="left" valign="top" width="60%">Number in array</td>
</tr>
<tr>
<td align="left" valign="top">&nbsp;</td>
<td align="left" valign="top">&nbsp;</td>
<td align="left" valign="top">BINARY(4)</td>
<td align="left" valign="top">Offset to first device path name</td>
</tr>
<tr>
<td align="left" valign="top" colspan="4"><strong>Note:</strong> These fields
repeat for each device name.</td>
</tr>
<tr>
<td align="left" valign="top">&nbsp;</td>
<td align="left" valign="top">&nbsp;</td>
<td align="left" valign="top">BINARY(4)</td>
<td align="left" valign="top">Offset to next device path name</td>
</tr>
<tr>
<td align="left" valign="top">&nbsp;</td>
<td align="left" valign="top">&nbsp;</td>
<td align="left" valign="top">CHAR(12)</td>
<td align="left" valign="top">Reserved</td>
</tr>
<tr>
<td align="left" valign="top">&nbsp;</td>
<td align="left" valign="top">&nbsp;</td>
<td align="left" valign="top">CHAR(*)</td>
<td align="left" valign="top">Device path name</td>
</tr>
</table>
<p><em>Device path name.</em> The path name of the device used for the restore
operation. The path name should be specified in the Qlg_Path_Name_T format. If
a pointer is specified in the path name format, it must be 16-byte aligned. If
not, unpredictable results may occur. For more information on this structure,
see <a href="../apiref/pns.htm">Path name format</a>. The possible value is:</p>
<table cellpadding="5">
<!-- cols="15 85" -->
<tr>
<td align="left" valign="top" nowrap><em>device-path-name</em></td>
<td align="left" valign="top">The path name of the
<img src="delta.gif" alt="Start of change">media definition,<img src="deltaend.gif" alt="End of change"> media library device, optical
device, save file, or tape device used to restore the objects. If a <img src="delta.gif" alt="Start of change">media definition,<img src="deltaend.gif" alt="End of change"> media library
device, optical device, or save file path name is specified, it must be the only
element in the array.
<p><img src="delta.gif" alt="Start of change">For information about creating and using a media definition, see the <a
href="../books/sc415304.pdf" target="_blank">Backup and Recovery</a><img
src="wbpdf.gif" alt="Link to PDF"> book and the <a href="qsrcrtmd.htm">Create
Media Definition</a> (QSRCRTMD, QsrCreateMediaDefinition) API.<img src="deltaend.gif" alt="End of change">
</td>
</tr>
</table>
<p><em>Number in array.</em> The number of devices used during the restore
operation. The possible value is:</p>
<table cellpadding="5">
<!-- cols="10 90" -->
<tr>
<td align="left" valign="top" nowrap><em>1-4</em></td>
<td align="left" valign="top">The number of devices used during the restore
operation.</td>
</tr>
</table>
<p><em>Offset to first device path name.</em> The offset from the beginning of
the user space to the first device path name in the list. The possible value
is:</p>
<table cellpadding="5">
<!-- cols="5 95" -->
<tr>
<td align="left" valign="top"><em>n</em></td>
<td align="left" valign="top">The offset from the beginning of the user space
to the first device path name in the list.</td>
</tr>
</table>
<p><em>Offset to next device path name.</em> The offset from the beginning of
the user space to the next device path name in the list. The possible value
is:</p>
<table cellpadding="5">
<!-- cols="5 95" -->
<tr>
<td align="left" valign="top"><em>n</em></td>
<td align="left" valign="top">The offset from the beginning of the user space
to the next device path name in the list. If the current device path name is
the last device path name in the array, this value should be 0.</td>
</tr>
</table>
<p><em>Reserved.</em> Reserved. The possible value is:</p>
<table cellpadding="5">
<!-- cols="10 90" -->
<tr>
<td align="left" valign="top"><em>x'00'</em></td>
<td align="left" valign="top">This field should contain x'00's.</td>
</tr>
</table>
<p><strong>Directory subtree.</strong> Whether the directory subtrees are
included in the restore operation. The default is 1. 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 subtrees are included in the restore
operation. If a directory matches the object name pattern specified, the
objects in the directory are included. If the directory has subdirectories,
neither the subdirectories nor the objects in the subdirectories are included.
(*NONE)</td>
</tr>
<tr>
<td align="left" valign="top"><em>1</em></td>
<td align="left" valign="top">The entire subtree of each directory that matches
the object name pattern is included. The subtree includes all subdirectories
and the objects within those subdirectories. (*ALL)</td>
</tr>
<tr>
<td align="left" valign="top"><em>2</em></td>
<td align="left" valign="top">The objects in the first level of each directory
that matches the object name pattern are included. The subdirectories of each
matching directory are included, but the objects in the subdirectories are not
included. (*DIR)</td>
</tr>
<tr>
<td align="left" valign="top"><em>3</em></td>
<td align="left" valign="top">Only the objects that exactly match the object
name pattern are included. If the object name pattern specifies a directory,
objects in the directory are not included. (*OBJ)</td>
</tr>
<tr>
<td align="left" valign="top"><em>4</em></td>
<td align="left" valign="top">The objects that match the object name pattern
are processed along with the storage for related objects. Objects that are
saved using this value can only be restored using SUBTREE(*STG). (*STG)</td>
</tr>
</table>
<p><strong>End of media option.</strong> The operation that is performed
automatically on the tape or optical volume after the restore operation ends.
If more than one volume is used, this key applies only to the last volume used;
all other volumes are unloaded when the end of the volume is reached. The
default is 0.</p>
<p><strong>Note:</strong> This parameter is valid only if a tape or optical
device name is specified. For optical devices, 2 is the only value supported; 0
and 1 are ignored.</p>
<p>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">The tape is automatically rewound, but not
unloaded, after the operation ends. (*REWIND)</td>
</tr>
<tr>
<td align="left" valign="top"><em>1</em></td>
<td align="left" valign="top">The tape does not rewind or unload after the
operation ends. It remains at the current position on the tape drive.
(*LEAVE)</td>
</tr>
<tr>
<td align="left" valign="top"><em>2</em></td>
<td align="left" valign="top">The tape is automatically rewound and unloaded
after the operation ends. Some optical devices eject the volume after the
operation ends. (*UNLOAD)</td>
</tr>
</table>
<p><strong>Force object conversion.</strong> Whether to convert user objects to
the format required for use in the current version of the operating system.</p>
<p><strong>Note:</strong> If an object needs to be converted, but is not
converted during the restore operation, the object is automatically converted
the first time it is used.</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%">&nbsp;</td>
<td align="center" valign="top" width="10%">&nbsp;</td>
<td align="left" valign="top" width="20%">CHAR(1)</td>
<td align="left" valign="top" width="60%">Force conversion</td>
</tr>
<tr>
<td align="center" valign="top">&nbsp;</td>
<td align="center" valign="top">&nbsp;</td>
<td align="left" valign="top">CHAR(1)</td>
<td align="left" valign="top">Objects to convert</td>
</tr>
</table>
<p><em>Force conversion.</em> Whether objects should be converted on the
restore operation. The default is 2. 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">The objects are not converted during the restore
operation. (*NO)</td>
</tr>
<tr>
<td align="left" valign="top"><em>1</em></td>
<td align="left" valign="top">The objects are converted during the restore
operation. (*YES)
<p><strong>Note:</strong> This value increases the time of the restore
operation, but avoids the need to convert the objects when they are first
used.</p>
</td>
</tr>
<tr>
<td align="left" valign="top"><em>2</em></td>
<td align="left" valign="top">The objects are converted based on the value of
the QFRCCVNRST system value. (*SYSVAL)
<p><strong>Note:</strong> If this value is specified and the system value
QFRCCVNRST has a value of 1, the restore operation proceeds as if 1 were
specified for the force conversion field and 2 were specified for the objects
to convert field.</p>
<p>If QFRCCVNRST has a value of 0, the restore operation proceeds as if 0 were
specified for the force conversion field.</p>
</td>
</tr>
</table>
<p><em>Objects to convert.</em> Which objects should be converted on the
restore operation. The default is 2. 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">All objects are converted regardless of their
current format. Even if the objects are in the current format, they are
converted again. However, if the objects are not observable, the objects are
not restored. (*ALL)</td>
</tr>
<tr>
<td align="left" valign="top"><em>2</em></td>
<td align="left" valign="top">The objects are converted only if they require
conversion to be used by the current operating system. If the objects are not
observable, the objects are restored but not converted. (*RQD)</td>
</tr>
</table>
<p><strong>Object ID.</strong> Whether the object ID of the restored object
will be the object ID of the object from the save media, the object ID of the
object that exists on the system prior to the restore, or a new object ID
generated by the system if the object does not exist on the system prior to the
restore. The default is 0. 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">The restored object will have the object ID it
had when it was saved. (*SAVED)</td>
</tr>
<tr>
<td align="left" valign="top"><em>1</em></td>
<td align="left" valign="top">The restored object may have a new object ID
generated by the system. If the object is being restored as a new object, a new
object ID will be given to the restored object. If an object with the same name
as the object from the media already exists on the system, the object ID of the
restored object will be the same as the object ID of the object on the system
before the restore. (*SYS)</td>
</tr>
</table>
<p><strong>Label.</strong> The file identifier of the media to be used for the
restore operation. The default is *SEARCH. The possible values are:</p>
<table cellpadding="5">
<!-- cols="15 85" -->
<tr>
<td align="left" valign="top"><em>*SEARCH</em></td>
<td align="left" valign="top">The file label for which to search is determined
by the system.</td>
</tr>
<tr>
<td align="left" valign="top" nowrap><em>file-identifier</em></td>
<td align="left" valign="top">The identifier (maximum of 17 characters) of the
tape file used for the restore operation.</td>
</tr>
</table>
<!-- Start PATTERN -->
<p><strong>Name pattern.</strong> Specifies a pattern to be used to include or omit objects.</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%">&nbsp;</td>
<td align="center" valign="top" width="10%">&nbsp;</td>
<td align="left" valign="top" width="20%">BINARY(4)</td>
<td align="left" valign="top" width="60%">Number in array</td>
</tr>
<tr>
<td align="center" valign="top">&nbsp;</td>
<td align="center" valign="top">&nbsp;</td>
<td align="left" valign="top">BINARY(4)</td>
<td align="left" valign="top">Offset to first pattern name</td>
</tr>
<tr>
<td align="left" valign="top" colspan="4"><strong>Note:</strong> These fields
repeat for each pattern name.</td>
</tr>
<tr>
<td align="center" valign="top">&nbsp;</td>
<td align="center" valign="top">&nbsp;</td>
<td align="left" valign="top">BINARY(4)</td>
<td align="left" valign="top">Offset to next pattern name</td>
</tr>
<tr>
<td align="center" valign="top">&nbsp;</td>
<td align="center" valign="top">&nbsp;</td>
<td align="left" valign="top">CHAR(1)</td>
<td align="left" valign="top">Option</td>
</tr>
<tr>
<td align="center" valign="top">&nbsp;</td>
<td align="center" valign="top">&nbsp;</td>
<td align="left" valign="top">CHAR(11)</td>
<td align="left" valign="top">Reserved</td>
</tr>
<tr>
<td align="center" valign="top">&nbsp;</td>
<td align="center" valign="top">&nbsp;</td>
<td align="left" valign="top">CHAR(*)</td>
<td align="left" valign="top">Pattern name</td>
</tr>
</table>
<p><em>Number in array.</em> The number of pattern names.
The possible value is:</p>
<table cellpadding="5">
<!-- cols="15 85" -->
<tr>
<td align="left" valign="top" nowrap><em>1-n</em></td>
<td align="left" valign="top">The number of pattern names.</td>
</tr>
</table>
<p><em>Pattern name.</em> Specifies a pattern name. The possible value is:</p>
<table cellpadding="5">
<!-- cols="15 85" -->
<tr>
<td align="left" valign="top" nowrap><em>pattern-name</em></td>
<td align="left" valign="top">The object name or pattern that can match
many names.</td>
</tr>
</table>
<p><em>Offset to first pattern name.</em> The offset from the beginning of
the user space to the first pattern name. The possible value is:</p>
<table cellpadding="5">
<!-- cols="5 95" -->
<tr>
<td align="left" valign="top"><em>n</em></td>
<td align="left" valign="top">The offset from the beginning of the user space
to the first pattern name.</td>
</tr>
</table>
<p><em>Offset to next pattern name.</em> The offset from the beginning of the user
space to the next pattern name in the list. The possible value is:</p>
<table cellpadding="5">
<!-- cols="5 95" -->
<tr>
<td align="left" valign="top"><em>n</em></td>
<td align="left" valign="top">The offset from the beginning of the user space
to the next pattern name in the list. If the current pattern name is the
last pattern in the array, this value should be 0.</td>
</tr>
</table>
<p><em>Option.</em> Whether names that match the pattern should be included or
omitted from the restore operation.</p>
<p><strong>Note:</strong> The subtree key specifies whether the subtrees are
included or omitted.</p>
<p>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">All objects which are included by the OBJ parameter are included in the restore except those objects which match the PATTERN parameter. This value overrides objects that are included with option 1 and is intended to be used to omit a subset of a previously selected patterns. (*OMIT)</td>
</tr>
<tr>
<td align="left" valign="top"><em>1</em></td>
<td align="left" valign="top">Only objects which are included by the OBJ parameter and match the PATTERN parameter are included in the restore, unless overridden by an omit specification. (*INCLUDE)</td>
</tr>
</table>
<p><em>Reserved</em> Reserved. The possible value is:</p>
<table cellpadding="5">
<!-- cols="10 90" -->
<tr>
<td align="left" valign="top"><em>x'00'</em></td>
<td align="left" valign="top">This field should contain x'00's.</td>
</tr>
</table>
<!-- End PATTERN -->
<p><strong>Object path name.</strong> The path name of the object to restore.
You can specify a pattern for this path name.</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%">&nbsp;</td>
<td align="center" valign="top" width="10%">&nbsp;</td>
<td align="left" valign="top" width="20%">BINARY(4)</td>
<td align="left" valign="top" width="60%">Number in array</td>
</tr>
<tr>
<td align="center" valign="top">&nbsp;</td>
<td align="center" valign="top">&nbsp;</td>
<td align="left" valign="top">BINARY(4)</td>
<td align="left" valign="top">Offset to first object path name</td>
</tr>
<tr>
<td align="left" valign="top" colspan="4"><strong>Note:</strong> These fields
repeat for each object path name.</td>
</tr>
<tr>
<td align="center" valign="top">&nbsp;</td>
<td align="center" valign="top">&nbsp;</td>
<td align="left" valign="top">BINARY(4)</td>
<td align="left" valign="top">Offset to next object</td>
</tr>
<tr>
<td align="center" valign="top">&nbsp;</td>
<td align="center" valign="top">&nbsp;</td>
<td align="left" valign="top">BINARY(4)</td>
<td align="left" valign="top">Offset to new object path name</td>
</tr>
<tr>
<td align="center" valign="top">&nbsp;</td>
<td align="center" valign="top">&nbsp;</td>
<td align="left" valign="top">CHAR(1)</td>
<td align="left" valign="top">Option</td>
</tr>
<tr>
<td align="center" valign="top">&nbsp;</td>
<td align="center" valign="top">&nbsp;</td>
<td align="left" valign="top">CHAR(7)</td>
<td align="left" valign="top">Reserved</td>
</tr>
<tr>
<td align="center" valign="top">&nbsp;</td>
<td align="center" valign="top">&nbsp;</td>
<td align="left" valign="top">CHAR(*)</td>
<td align="left" valign="top">Object path name</td>
</tr>
<tr>
<td align="center" valign="top">&nbsp;</td>
<td align="center" valign="top">&nbsp;</td>
<td align="left" valign="top">CHAR(*)</td>
<td align="left" valign="top">New path name</td>
</tr>
</table>
<p><em>New path name.</em> The new path name of the object. The path name
should be specified in the Qlg_Path_Name_T format. If a pointer is specified in
the path name format, it must be 16-byte aligned. If not, unpredictable results
may occur. For more information on this structure, see
<a href="../apiref/pns.htm">Path name format</a>. The possible value is:</p>
<table cellpadding="5">
<!-- cols="15 85" -->
<tr>
<td align="left" valign="top" nowrap><em>path-name</em></td>
<td align="left" valign="top">The path name with which to restore the object.
If a pattern is specified for the object path name field, the new path name
must be an existing directory in which to restore any objects that match the
pattern. If an object name is specified in the object path name field, each
component in the new path name must exist with the exception of the last
component. If the object described in the last component does not exist, it
will be restored as new.</td>
</tr>
</table>
<p><em>Number in array.</em> The number of object path names to be restored.
The possible value is:</p>
<table cellpadding="5">
<!-- cols="10 90" -->
<tr>
<td align="left" valign="top" nowrap><em>1-300</em></td>
<td align="left" valign="top">The number of object path names to be
restored.</td>
</tr>
</table>
<p><em>Object path name.</em> The path names of the objects saved on the media.
Directory abbreviations (for example, the current directory) are expanded with
their current values, not with the values they had at the time of the save
operation. The path name should be specified in the Qlg_Path_Name_T format. If
a pointer is specified in the path name format, it must be 16-byte aligned. If
not, unpredictable results may occur. For more information on this structure,
see <a href="../apiref/pns.htm">Path name format</a>. The possible value is:</p>
<table cellpadding="5">
<!-- cols="15 85" -->
<tr>
<td align="left" valign="top" nowrap><em>path-name</em></td>
<td align="left" valign="top">The path name or pattern that can match many
names. If 0 is specified for the new name option, each component in the path
name must exist with the exception of the last component. The name in the last
component is restored as new if it does not exist.</td>
</tr>
</table>
<p><em>Offset to first object path name.</em> The offset from the beginning of
the user space to the first object path name. The possible value is:</p>
<table cellpadding="5">
<!-- cols="5 95" -->
<tr>
<td align="left" valign="top"><em>n</em></td>
<td align="left" valign="top">The offset from the beginning of the user space
to the first object path name.</td>
</tr>
</table>
<p><em>Offset to new object path name.</em> The offset from the beginning of
the user space to the new object path name. 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">There is not a new object path name. The object
will be restored to the same name with which it was saved.</td>
</tr>
<tr>
<td align="left" valign="top"><em>n</em></td>
<td align="left" valign="top">The offset from the beginning of the user space
to the new object path name.</td>
</tr>
</table>
<p><em>Offset to next object.</em> The offset from the beginning of the user
space to the next object in the list. The possible value is:</p>
<table cellpadding="5">
<!-- cols="5 95" -->
<tr>
<td align="left" valign="top"><em>n</em></td>
<td align="left" valign="top">The offset from the beginning of the user space
to the next object in the list. If the current object is the last object in the
array, this value should be 0.</td>
</tr>
</table>
<p><em>Option.</em> Whether names that match the pattern should be included or
omitted from the restore operation. Note that in determining whether the name
matches a pattern, relative name patterns are always treated as relative to the
current working directory.</p>
<p><strong>Note:</strong> The subtree key specifies whether the subtrees are
included or omitted.</p>
<p>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">The objects that match the object name pattern
are not restored. This value overrides the objects that are included with
option 1 and is intended to be used to omit a subset of a previously selected
pattern. (*OMIT)</td>
</tr>
<tr>
<td align="left" valign="top"><em>1</em></td>
<td align="left" valign="top">The objects that match the object name pattern
are restored, unless overridden by an omit specification. (*INCLUDE)</td>
</tr>
</table>
<p><em>Reserved</em> Reserved. The possible value is:</p>
<table cellpadding="5">
<!-- cols="10 90" -->
<tr>
<td align="left" valign="top"><em>x'00'</em></td>
<td align="left" valign="top">This field should contain x'00's.</td>
</tr>
</table>
<p><strong>Optical file.</strong> The path name of the optical file that is
used for the restore operation. The path name should be specified in the
Qlg_Path_Name_T format. If a pointer is specified in the path name format, it
must be 16-byte aligned. If not, unpredictable results may occur. For more
information on this structure, see <a href="../apiref/pns.htm">Path name format</a>. The
default is '*'. The possible values are:</p>
<table cellpadding="5">
<!-- cols="15 85" -->
<tr>
<td align="left" valign="top"><em>'*'</em></td>
<td align="left" valign="top">The system searches the root directory of the
optical volume for the default name generated by the corresponding save
operation.</td>
</tr>
<tr>
<td align="left" valign="top"><em>'Optical-directory-path-name/*'</em></td>
<td align="left" valign="top">The system searches the specified directory of
the optical volume for the default name generated by the corresponding save
operation.</td>
</tr>
<tr>
<td align="left" valign="top" nowrap><em>Optical file path name</em></td>
<td align="left" valign="top">The path name of the optical file that is used
for the restore operation, beginning with the root directory of the
volume.</td>
</tr>
</table>
<p><strong>Option.</strong> Whether to restore objects that already exist on
the system or to restore objects that do not already exist on the system. The
default is 0. 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">All of the specified objects are restored,
whether or not they already exist on the system. (*ALL)</td>
</tr>
<tr>
<td align="left" valign="top"><em>1</em></td>
<td align="left" valign="top">Objects are restored only if they do not already
exist on the system. (*NEW)</td>
</tr>
<tr>
<td align="left" valign="top"><em>2</em></td>
<td align="left" valign="top">Objects are restored only if they already exist
on the system. (*OLD)</td>
</tr>
</table>
<p><strong>Output.</strong> Whether a list of information about the restored
objects is created. The information can be directed to a spooled file, a stream
file, or a user space.</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%">&nbsp;</td>
<td align="center" valign="top" width="10%">&nbsp;</td>
<td align="left" valign="top" width="20%">CHAR(1)</td>
<td align="left" valign="top" width="60%">Option</td>
</tr>
<tr>
<td align="center" valign="top">&nbsp;</td>
<td align="center" valign="top">&nbsp;</td>
<td align="left" valign="top">CHAR(1)</td>
<td align="left" valign="top">Type of output information</td>
</tr>
<tr>
<td align="center" valign="top">&nbsp;</td>
<td align="center" valign="top">&nbsp;</td>
<td align="left" valign="top">CHAR(14)</td>
<td align="left" valign="top">Reserved</td>
</tr>
<tr>
<td align="center" valign="top">&nbsp;</td>
<td align="center" valign="top">&nbsp;</td>
<td align="left" valign="top">CHAR(*)</td>
<td align="left" valign="top">Output path name</td>
</tr>
</table>
<p><em>Option.</em> Whether a list of information about the restored objects is
created. The default is 0. 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 output is created. (*NONE)</td>
</tr>
<tr>
<td align="left" valign="top"><em>1</em></td>
<td align="left" valign="top">The output is printed with the job's spooled
output. (*PRINT)</td>
</tr>
<tr>
<td align="left" valign="top"><em>2</em></td>
<td align="left" valign="top">The output is directed to an existing stream file
or user space specified by the output path name.</td>
</tr>
</table>
<p><em>Output path name.</em> The path name should be specified in the
Qlg_Path_Name_T format. If a pointer is specified in the path name format, it
must be 16-byte aligned. If not, unpredictable results may occur. For more
information on this structure, <a href="../apiref/pns.htm">Path name format</a>. The
possible value is:</p>
<table cellpadding="5">
<!-- cols="15 85" -->
<tr>
<td align="left" valign="top" nowrap><em>path-name</em></td>
<td align="left" valign="top">The path name of the existing stream file or user
space to which the output of the command is directed.</td>
</tr>
</table>
<p><em>Reserved</em> Reserved. The possible value is:</p>
<table cellpadding="5">
<!-- cols="10 90" -->
<tr>
<td align="left" valign="top"><em>x'00'</em></td>
<td align="left" valign="top">This field should contain x'00's.</td>
</tr>
</table>
<p><em>Type of output information.</em> The type of information that should be
directed to the spooled file, stream file, or user space specified for the
output key. 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">The file will contain information about the
command, and an entry for each directory. (*SUMMARY)</td>
</tr>
<tr>
<td align="left" valign="top"><em>1</em></td>
<td align="left" valign="top">The file will contain information about the
command, an entry for each directory, and an entry for each object that was not
successfully restored. (*ERR)</td>
</tr>
<tr>
<td align="left" valign="top"><em>2</em></td>
<td align="left" valign="top">The file will contain information about the
command, an entry for each directory, an entry for each object that was
successfully restored, and an entry for each object that was not successfully
restored. (*ALL)</td>
</tr>
</table>
<p><img src="delta.gif" alt="Start of change">
<br><strong>Parent directory owner.</strong>
The name of an existing user profile that will own parent directories that are
created by the restore. This key only applies to "root" (/), QOpenSys and
user-defined file systems, it will be ignored for all other file systems..
The default is *PARENT. The possible values are:</p>
<table cellpadding="5">
<!-- cols="15 85" -->
<tr>
<td align="left" valign="top"><em>*PARENT</em></td>
<td align="left" valign="top">The owner of the parent directory being created by the restore will be copied from the directory it is being created into. (*PARENT)</td>
</tr>
<tr>
<td align="left" valign="top"><em>name</em></td>
<td align="left" valign="top">Specify a user profile to be the owner of any parent
directories that are created by the restore. (name)<img src="deltaend.gif" alt="End of change"></td>
</tr>
</table>
<p><strong>Save date.</strong> The date the objects were saved. If the most
recently saved version is the one being restored, or if multiple saved versions
reside on the media, specify the date that identifies which version of the
objects to restore. If this key is not specified, the restored version of the
objects is the first version found. The possible value is:</p>
<table cellpadding="5">
<!-- cols="10 90" -->
<tr>
<td align="left" valign="top"><em>date</em></td>
<td align="left" valign="top">The date the objects were saved, in the format
CYYMMDD:
<dl compact>
<dt><em>C</em></dt>
<dd>Century, where 0 indicates years 19<em>xx</em>
and 1 indicates years 20<em>xx</em>.<br><br></dd>
<dt><em>YY</em></dt>
<dd>Year<br><br></dd>
<dt><em>MM</em></dt>
<dd>Month<br><br></dd>
<dt><em>DD</em></dt>
<dd>Day</dd>
</dl>
</td>
</tr>
</table>
<p><strong>Save time.</strong> The time the objects were saved. If this key is
not specified, the version of the objects to be restored is the first version
on the volume.</p>
<p><strong>Note:</strong></p>
<ol>
<li>This key is valid only if the save date key is specified.</li>
<li>This key is ignored when the sequence number key is specified.</li>
</ol>
<p>The possible value is:</p>
<table cellpadding="5">
<!-- cols="10 90" -->
<tr>
<td align="left" valign="top"><em>time</em></td>
<td align="left" valign="top">The time the objects were saved in the format
HHMMSS:
<dl compact>
<dt><em>HH</em></dt>
<dd>Hour<br><br></dd>
<dt><em>MM</em></dt>
<dd>Minute<br><br></dd>
<dt><em>SS</em></dt>
<dd>Second</dd>
</dl>
</td>
</tr>
</table>
<p><strong>Sequence number.</strong> The tape file sequence number to be used.
The default is -1. The possible values are:</p>
<table cellpadding="5">
<!-- cols="15 85" -->
<tr>
<td align="left" valign="top"><em>-1</em></td>
<td align="left" valign="top">The tape volume is searched for the next file
that contains any of the specified objects. (*SEARCH)</td>
</tr>
<tr>
<td align="left" valign="top" nowrap><em>1-16777215</em></td>
<td align="left" valign="top">The sequence number of the file.</td>
</tr>
</table>
<p><strong>System.</strong> Whether to process objects that exist on the local
system or remote systems. The default is 0. 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">Only local objects are processed. (*LCL)</td>
</tr>
<tr>
<td align="left" valign="top"><em>1</em></td>
<td align="left" valign="top">Only remote objects are processed. (*RMT)</td>
</tr>
<tr>
<td align="left" valign="top"><em>2</em></td>
<td align="left" valign="top">Both local and remote objects are processed.
(*ALL)</td>
</tr>
</table>
<p><strong>Volume identifier.</strong> The volume identifiers of the volumes,
or the cartridge identifier of a tape in a tape media library device, from
which data is to be restored. The volumes must be placed in the device in the
order specified on this key. After all specified volumes are filled, the
restore operation continues on whatever volumes are mounted on the device.</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%">&nbsp;</td>
<td align="center" valign="top" width="10%">&nbsp;</td>
<td align="left" valign="top" width="20%">BINARY(4)</td>
<td align="left" valign="top" width="60%">Number in array</td>
</tr>
<tr>
<td align="center" valign="top">&nbsp;</td>
<td align="center" valign="top">&nbsp;</td>
<td align="left" valign="top">BINARY(4)</td>
<td align="left" valign="top">Length of each volume identifier</td>
</tr>
<tr>
<td align="center" valign="top">&nbsp;</td>
<td align="center" valign="top">&nbsp;</td>
<td align="left" valign="top">BINARY(4)</td>
<td align="left" valign="top">Offset to first volume identifier</td>
</tr>
<tr>
<td align="left" valign="top" colspan="4"><strong>Note:</strong> These fields
repeat for each volume identifier</td>
</tr>
<tr>
<td align="center" valign="top">&nbsp;</td>
<td align="center" valign="top">&nbsp;</td>
<td align="left" valign="top">BINARY(4)</td>
<td align="left" valign="top">Offset to next volume identifier</td>
</tr>
<tr>
<td align="center" valign="top">&nbsp;</td>
<td align="center" valign="top">&nbsp;</td>
<td align="left" valign="top">CHAR(*)</td>
<td align="left" valign="top">Volume identifier</td>
</tr>
</table>
<p><em>Length of each volume identifier.</em> The character length of each of
the volume identifiers. The possible value follows:</p>
<table cellpadding="5">
<!-- cols="5 95" -->
<tr>
<td align="left" valign="top"><em>n</em></td>
<td align="left" valign="top">The size of a single volume identifier. The
maximum size of a tape volume identifier is 6 characters. The
maximum size of an optical volume identifier is 32 characters. If a volume
identifier larger than the maximum size is entered for this key, it is
truncated to the maximum size.</td>
</tr>
</table>
<p><em>Number in array.</em> The number of volume identifiers that are used
during the restore operation. The default is 0. 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">The volume currently placed in the device is
used. If 0 is specified for a tape media library device, volume identifiers
must be supplied by using the Tape Management exit program during the save or
restore operation. If 0 is specified, the length of each volume identifier
value is ignored. (*MOUNTED)
<p><strong>Note:</strong> This value cannot be specified for an optical media
library device.</p>
</td>
</tr>
<tr>
<td align="left" valign="top" nowrap><em>1-75</em></td>
<td align="left" valign="top">The number of volume identifiers used during the
restore operation.</td>
</tr>
</table>
<p><em>Offset to first volume identifier</em> The offset from the beginning of
the user space to the first volume identifier in the list. The possible value
is:</p>
<table cellpadding="5">
<!-- cols="5 95" -->
<tr>
<td align="left" valign="top"><em>n</em></td>
<td align="left" valign="top">The offset from the beginning of the user space
to the first volume identifier in the list.</td>
</tr>
</table>
<p><em>Offset to next volume identifier</em> The offset from the beginning of
the user space to the next object volume identifier in the list. The possible
value is:</p>
<table cellpadding="5">
<!-- cols="5 95" -->
<tr>
<td align="left" valign="top"><em>n</em></td>
<td align="left" valign="top">The offset from the beginning of the user space
to the next volume identifier in the list. If the current volume identifier is
the last volume identifier in the array, this value should be 0.</td>
</tr>
</table>
<p><em>Volume identifier.</em> The volume identifiers of one or more volumes to
be used. The possible value is:</p>
<table cellpadding="5">
<!-- cols="15 85" -->
<tr>
<td align="left" valign="top" nowrap><em>Volume identifier</em></td>
<td align="left" valign="top">The volume identifiers of one or more volumes to
be used.</td>
</tr>
</table>
<br>
<br>
<h3>Dependencies between Keys</h3>
<p>The following two tables list the dependencies between the different keys.
If the dependency pertains only to a certain value, then that value is also
shown (key&nbsp;=&nbsp;<em>n</em>, where <em>n</em> is the value). Otherwise,
if the dependency is true for all values of the key, then only the name of the
key is given.</p>
<p>The following table lists the conditions where specifying a certain key
forces the use of another key.<br>
</p>
<table border width="80%">
<!-- cols="30 70" -->
<tr>
<th align="left" valign="bottom">If you specify...</th>
<th align="left" valign="bottom">...must be specified</th>
</tr>
<tr>
<td align="left" valign="top" width="50%">Device = optical library device</td>
<td align="left" valign="top" width="50%">Volume identifier</td>
</tr>
</table>
<br>
<br>
<p>The following table lists the conditions where specifying a certain key
excludes the user from using another key or a particular value of that key.</p>
<table border width="80%">
<!-- cols="30 70" -->
<tr>
<th align="left" valign="bottom">If you specify...</th>
<th align="left" valign="bottom">...cannot be specified</th>
</tr>
<tr>
<td align="left" valign="top" width="50%"><img src="delta.gif" alt="Start of change">Create parent directories = 0</td>
<td align="left" valign="top" width="50%">Parent directory owner<img src="deltaend.gif" alt="End of change"></td>
</tr>
<tr>
<td align="left" valign="top"><img src="delta.gif" alt="Start of change">Device = media definition</td>
<td align="left" valign="top">
Optical file<br>
Sequence number<br>
Volume identifier<img src="deltaend.gif" alt="End of change"></td>
</tr>
<tr>
<td align="left" valign="top">Device = optical device</td>
<td align="left" valign="top">Label<br>
Sequence number</td>
</tr>
<tr>
<td align="left" valign="top">Device = save file</td>
<td align="left" valign="top">End of media option<br>
Label<br>
Optical file<br>
Sequence number<br>
Volume identifier</td>
</tr>
<tr>
<td align="left" valign="top">Device = tape device</td>
<td align="left" valign="top">Optical file</td>
</tr>
</table>
<br>
<br>
<h3>Relationship to RST Command</h3>
<p>Because of the relationship between the QsrRestore API and the RST command,
the following situations should be noted:</p>
<ul>
<li>Message text: Several messages produced by this API refer to parameters or
values of the RST command (for example, *SEARCH). To determine which key a
given parameter corresponds to, see <a href="#HDRKEYFLD3">Valid Keys</a>. To
determine which key value a given parameter value corresponds to, see
<a href="#HDRSOLDES1">Field Descriptions</a>.</li>
<li>Command type: The command type listed for the API on headings of displays
and print files is QsrRestore for integrated file system objects. If QsrRestore
is used to restore objects in libraries or document library objects (DLOs), the
generated output indicates that the corresponding library or DLO command
generated the media.</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%">CPF0001 E</td>
<td align="left" valign="top" width="85%">Error found on &amp;1 command.</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">CPF3700 E</td>
<td align="left" valign="top">All CPF37xx messages could be signalled. xx is
from 01 to FF.</td>
</tr>
<tr>
<td align="left" valign="top">CPF3800 E</td>
<td align="left" valign="top">All CPF38xx messages could be signalled. xx is
from 01 to FF.</td>
</tr>
<tr>
<td align="left" valign="top">CPF3C31 E</td>
<td align="left" valign="top">Object type &amp;1 is not valid.</td>
</tr>
<tr>
<td align="left" valign="top">CPF3C4D E</td>
<td align="left" valign="top">Length &amp;1 for key &amp;2 not valid.</td>
</tr>
<tr>
<td align="left" valign="top">CPF3C81 E</td>
<td align="left" valign="top">Value for key &amp;1 not valid.</td>
</tr>
<tr>
<td align="left" valign="top">CPF3C82 E</td>
<td align="left" valign="top">Key &amp;1 not valid for API &amp;2.</td>
</tr>
<tr>
<td align="left" valign="top">CPF3C83 E</td>
<td align="left" valign="top">Key &amp;1 not allowed with value specified for
key &amp;2.</td>
</tr>
<tr>
<td align="left" valign="top">CPF3C84 E</td>
<td align="left" valign="top">Key &amp;1 required with value specified for key
&amp;2.</td>
</tr>
<tr>
<td align="left" valign="top">CPF3C85 E</td>
<td align="left" valign="top">Value for key &amp;1 not allowed with value for
key &amp;2.</td>
</tr>
<tr>
<td align="left" valign="top">CPF3C86 E</td>
<td align="left" valign="top">Required key &amp;1 not specified.</td>
</tr>
<tr>
<td align="left" valign="top">CPF3C87 E</td>
<td align="left" valign="top">Key &amp;1 allows one value with special
value.</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">CPF5729 E</td>
<td align="left" valign="top">Not able to allocate object &amp;1.</td>
</tr>
<tr>
<td align="left" valign="top">CPF9800 E</td>
<td align="left" valign="top">All CPF98xx messages could be signaled. xx is
from 01 to FF.</td>
</tr>
<tr>
<td align="left" valign="top">CPF9999 E</td>
<td align="left" valign="top">Function check. &amp;1 unmonitored by &amp;2 at
statement &amp;5, instruction &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>
Reference in New Issue View Git Blame Copy Permalink