329 lines
9.8 KiB
HTML
329 lines
9.8 KiB
HTML
|
<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
|
||
|
|
<html>
|
||
|
|
<head>
|
||
|
|
<meta http-equiv="Content-Type" content="text/html; charset=utf-8">
|
||
|
|
<meta name="Copyright" content="Copyright (c) 2006 by IBM Corporation">
|
||
|
|
<title>Restore from Application Exit Program</title>
|
||
|
|
<!-- 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. -->
|
||
|
|
<!-- Begin Header Records =========================================== -->
|
||
|
|
<!-- BACKMST SCRIPT A converted by B2H R4.1 (346) (CMS) by v2kea304 at -->
|
||
|
|
<!-- RCHVMW2 on 26 April 1999 at 10:21:58 -->
|
||
|
|
<!-- SPHANK on 8 October 2001 at 07:52 - Updated length of restore data -->
|
||
|
|
<!-- 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>Restore from Application Exit Program</h2>
|
||
|
|
|
||
|
|
<div class="box" style="width: 70%;">
|
||
|
|
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%">Operation type</td>
|
||
|
|
<td align="left" valign="top" width="20%">Input</td>
|
||
|
|
<td align="left" valign="top" width="20%">Binary(4)</td>
|
||
|
|
</tr>
|
||
|
|
|
||
|
|
<tr>
|
||
|
|
<td align="center" valign="top">2</td>
|
||
|
|
<td align="left" valign="top">Operation status</td>
|
||
|
|
<td align="left" valign="top">Output</td>
|
||
|
|
<td align="left" valign="top">Binary(4)</td>
|
||
|
|
</tr>
|
||
|
|
|
||
|
|
<tr>
|
||
|
|
<td align="center" valign="top">3</td>
|
||
|
|
<td align="left" valign="top">Restore data</td>
|
||
|
|
<td align="left" valign="top">Input</td>
|
||
|
|
<td align="left" valign="top">Char(*)</td>
|
||
|
|
</tr>
|
||
|
|
|
||
|
|
<tr>
|
||
|
|
<td align="center" valign="top">4</td>
|
||
|
|
<td align="left" valign="top">Length of restore data</td>
|
||
|
|
<td align="left" valign="top">Input</td>
|
||
|
|
<td align="left" valign="top">Binary(4)</td>
|
||
|
|
</tr>
|
||
|
|
|
||
|
|
<tr>
|
||
|
|
<td align="center" valign="top">5</td>
|
||
|
|
<td align="left" valign="top">Restore bytes written</td>
|
||
|
|
<td align="left" valign="top">Output</td>
|
||
|
|
<td align="left" valign="top">Binary(4)</td>
|
||
|
|
</tr>
|
||
|
|
|
||
|
|
<tr>
|
||
|
|
<td align="center" valign="top">6</td>
|
||
|
|
<td align="left" valign="top">Qualified user space name</td>
|
||
|
|
<td align="left" valign="top">Input</td>
|
||
|
|
<td align="left" valign="top">Char(20)</td>
|
||
|
|
</tr>
|
||
|
|
|
||
|
|
<tr>
|
||
|
|
<td align="center" valign="top">7</td>
|
||
|
|
<td align="left" valign="top">User space format name</td>
|
||
|
|
<td align="left" valign="top">Input</td>
|
||
|
|
<td align="left" valign="top">Char(8)<br>
|
||
|
|
</td>
|
||
|
|
</tr>
|
||
|
|
</table>
|
||
|
|
</div>
|
||
|
|
|
||
|
|
<p>The Restore from Application exit program enables an application program to
|
||
|
|
provide the restore records that are required for a restore-from-save-file
|
||
|
|
operation using the <a href="QaneRsta.htm">Restore from Application</a>
|
||
|
|
(QaneRsta) API.</p>
|
||
|
|
|
||
|
|
<p>The API calls the exit program once to start the transfer sequence, multiple
|
||
|
|
times to transfer each block of restore records, and once to end the transfer
|
||
|
|
sequence.</p>
|
||
|
|
|
||
|
|
<p>The API passes to the exit program the operation type, the number of restore
|
||
|
|
record bytes required, the qualified name of the user space and the format name
|
||
|
|
of the user space.</p>
|
||
|
|
|
||
|
|
<p>The exit program must return the restore data, the number of the restore
|
||
|
|
record bytes retrieved, and status on the success or failure of the requested
|
||
|
|
operation.</p>
|
||
|
|
|
||
|
|
<p>At any time following the initial call, the API could call the exit program
|
||
|
|
that requires an abnormal end to the transfer sequence.</p>
|
||
|
|
|
||
|
|
<br>
|
||
|
|
|
||
|
|
|
||
|
|
<h3>Restrictions</h3>
|
||
|
|
|
||
|
|
<p>The exit program must provide the restore records in the order the records
|
||
|
|
were saved, without modification, for the objects to be successfully
|
||
|
|
restored.</p>
|
||
|
|
|
||
|
|
<br>
|
||
|
|
|
||
|
|
|
||
|
|
<h3>Authorities and Locks</h3>
|
||
|
|
|
||
|
|
<p>See <a href="QaneRsta.htm">Restore from Application</a> (QaneRsta) API.</p>
|
||
|
|
|
||
|
|
<br>
|
||
|
|
|
||
|
|
|
||
|
|
<h3>Required Parameter Group</h3>
|
||
|
|
|
||
|
|
<dl>
|
||
|
|
<dt><strong>Operation type</strong></dt>
|
||
|
|
|
||
|
|
<dd>INPUT; BINARY(4)
|
||
|
|
|
||
|
|
<p>The type of operation that the exit program is required to run.</p>
|
||
|
|
|
||
|
|
<table cellpadding="5">
|
||
|
|
<!-- cols="5 95" -->
|
||
|
|
<tr>
|
||
|
|
<td align="left" valign="top"><em>1</em></td>
|
||
|
|
<td align="left" valign="top">Start<br>
|
||
|
|
The exit program must use this operation type to prepare for the restore
|
||
|
|
records transfer.</td>
|
||
|
|
</tr>
|
||
|
|
|
||
|
|
<tr>
|
||
|
|
<td align="left" valign="top"><em>2</em></td>
|
||
|
|
<td align="left" valign="top">Transfer<br>
|
||
|
|
The exit program must use this operation type to transfer (retrieve, write, and
|
||
|
|
so forth) a block of restore records.</td>
|
||
|
|
</tr>
|
||
|
|
|
||
|
|
<tr>
|
||
|
|
<td align="left" valign="top"><em>3</em></td>
|
||
|
|
<td align="left" valign="top">End<br>
|
||
|
|
The exit program must use this operation type to end the restore records
|
||
|
|
transfer.</td>
|
||
|
|
</tr>
|
||
|
|
|
||
|
|
<tr>
|
||
|
|
<td align="left" valign="top"><em>4</em></td>
|
||
|
|
<td align="left" valign="top">Abnormal end<br>
|
||
|
|
The exit program must use this operation type to prematurely end the restore
|
||
|
|
records transfer.</td>
|
||
|
|
</tr>
|
||
|
|
</table>
|
||
|
|
|
||
|
|
<p>Normal-operation-type order is 1 (start), 2 (transfer), 2 (transfer), ..., 2
|
||
|
|
(transfer), 3 (end).</p>
|
||
|
|
|
||
|
|
<p>Operation type 1 (start) is issued only once at the beginning of the restore
|
||
|
|
operation before any restore records are transferred.</p>
|
||
|
|
|
||
|
|
<p>Operation type 2 (transfer) is issued multiple times during the restore
|
||
|
|
operation as each block of restore records is required. The exit program must
|
||
|
|
provide as many restore record bytes as requested, with the exception of the
|
||
|
|
last block, which may not be of sufficient length.</p>
|
||
|
|
|
||
|
|
<p>Operation type 3 (end) is issued only once at the end of the restore
|
||
|
|
operation after all restore records are transferred. The exit program must be
|
||
|
|
able to handle the condition where this operation type is issued before all
|
||
|
|
restore records are transferred. The exit program must handle this operation
|
||
|
|
sequence as a normal condition and end the transfer sequence normally.</p>
|
||
|
|
|
||
|
|
<p>Operation type 4 (abnormal end) is issued only once following operation
|
||
|
|
types 1 (start) or 2 (transfer), under abnormal conditions to prematurely end
|
||
|
|
restore records transfer. These conditions are:</p>
|
||
|
|
|
||
|
|
<ul>
|
||
|
|
<li>The API detects an error with the system restore operation.</li>
|
||
|
|
|
||
|
|
<li>The exit program returns an operation status of 1 (error).</li>
|
||
|
|
</ul>
|
||
|
|
|
||
|
|
<br>
|
||
|
|
</dd>
|
||
|
|
|
||
|
|
<dt><strong>Operation status</strong></dt>
|
||
|
|
|
||
|
|
<dd>OUTPUT; BINARY(4)
|
||
|
|
|
||
|
|
<p>The ending status of the requested operation.</p>
|
||
|
|
|
||
|
|
<table cellpadding="5">
|
||
|
|
<!-- cols="5 95" -->
|
||
|
|
<tr>
|
||
|
|
<td align="left" valign="top"><em>0</em></td>
|
||
|
|
<td align="left" valign="top">Good<br>
|
||
|
|
The exit program must return this status value to indicate successful
|
||
|
|
completion of the operation.</td>
|
||
|
|
</tr>
|
||
|
|
|
||
|
|
<tr>
|
||
|
|
<td align="left" valign="top"><em>1</em></td>
|
||
|
|
<td align="left" valign="top">Error<br>
|
||
|
|
The exit program must return this status value to indicate unsuccessful
|
||
|
|
completion of the operation.</td>
|
||
|
|
</tr>
|
||
|
|
|
||
|
|
<tr>
|
||
|
|
<td align="left" valign="top"><em>2</em></td>
|
||
|
|
<td align="left" valign="top">Complete<br>
|
||
|
|
The exit program must use this status value instead of a status value of 0
|
||
|
|
(good)., when the last byte of the restore records has been retrieved. This
|
||
|
|
indicates successful completion of operation type 2 (transfer).</td>
|
||
|
|
</tr>
|
||
|
|
</table>
|
||
|
|
|
||
|
|
<br>
|
||
|
|
</dd>
|
||
|
|
|
||
|
|
<dt><strong>Restore data</strong></dt>
|
||
|
|
|
||
|
|
<dd>INPUT; CHAR(*)
|
||
|
|
|
||
|
|
<p>A block of restore records. The parameter is passed only on operation type 2
|
||
|
|
(transfer).</p>
|
||
|
|
</dd>
|
||
|
|
|
||
|
|
<dt><strong>Length of restore data</strong></dt>
|
||
|
|
|
||
|
|
<dd>INPUT; BINARY(4)
|
||
|
|
|
||
|
|
<p>For operation types 1 (start), 3 (end), and 4 (abnormal end), this value is
|
||
|
|
zero.</p>
|
||
|
|
|
||
|
|
<p>For operation type 2 (transfer), this is the length of restore data being
|
||
|
|
requested. <!-- Begin V5R2 change - SPH - 10/08/2001 -->
|
||
|
|
The maximum length is
|
||
|
|
1 048 832 bytes.
|
||
|
|
<!-- End V5R2 change - SPH - 08/20/2001 --></p>
|
||
|
|
</dd>
|
||
|
|
|
||
|
|
<dt><strong>Restore bytes written</strong></dt>
|
||
|
|
|
||
|
|
<dd>OUTPUT; BINARY(4)
|
||
|
|
|
||
|
|
<p>For operation types 1 (start), 3 (end), and 4 (abnormal end), this value
|
||
|
|
must be set to zero.</p>
|
||
|
|
|
||
|
|
<p>For operation type 2 (transfer), this value must be set to the actual number
|
||
|
|
of restore record bytes returned. This value must never exceed the value passed
|
||
|
|
in the length of restore data parameter.</p>
|
||
|
|
</dd>
|
||
|
|
|
||
|
|
<dt><strong>Qualified user space name</strong></dt>
|
||
|
|
|
||
|
|
<dd>INPUT; CHAR(20)
|
||
|
|
|
||
|
|
<p>The qualified user space name that is specified by the application on the
|
||
|
|
call to the Restore from Application (QaneRsta) API. 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.</p>
|
||
|
|
</dd>
|
||
|
|
|
||
|
|
<dt><strong>User space format name</strong></dt>
|
||
|
|
|
||
|
|
<dd>INPUT; CHAR(8)
|
||
|
|
|
||
|
|
<p>The user space format name that is specified by the application on the call
|
||
|
|
to the Restore from Application API. For the format of the structure, see the
|
||
|
|
SVRS0100 Format in the <a href="QaneRsta.htm">Restore from Application</a>
|
||
|
|
(QaneRsta) API. The exit program uses the length of application data field to
|
||
|
|
determine if the structure contains application data, and the offset to
|
||
|
|
application data field to locate this information.</p>
|
||
|
|
</dd>
|
||
|
|
</dl>
|
||
|
|
|
||
|
|
<br>
|
||
|
|
|
||
|
|
|
||
|
|
<h3>Coding Guidelines</h3>
|
||
|
|
|
||
|
|
<p>Applications should consider the following when coding the exit program:</p>
|
||
|
|
|
||
|
|
<ul>
|
||
|
|
<li>The program should only return an exception for the requested operation if
|
||
|
|
there has been a failure in the operation. If the program signals an escape
|
||
|
|
message to the API, the system assumes there is a failure. A diagnostic message
|
||
|
|
is returned to the calling program.<br>
|
||
|
|
<br>
|
||
|
|
</li>
|
||
|
|
|
||
|
|
<li>The program must clean up any locks that it acquires.<br>
|
||
|
|
<br>
|
||
|
|
</li>
|
||
|
|
|
||
|
|
<li>The program must handle all potential error conditions associated with its
|
||
|
|
own operations (be fault tolerant).<br>
|
||
|
|
<br>
|
||
|
|
</li>
|
||
|
|
|
||
|
|
<li>The program must avoid infinite looping conditions.</li>
|
||
|
|
</ul>
|
||
|
|
|
||
|
|
<hr>
|
||
|
|
Exit program 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>
|
||
|
|
|