320 lines
9.2 KiB
HTML
320 lines
9.2 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>Save to 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 sava data -->
|
||
|
|
<!-- 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>Save to 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">Save 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 save 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">Save bytes read</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)</td>
|
||
|
|
</tr>
|
||
|
|
</table>
|
||
|
|
|
||
|
|
<br>
|
||
|
|
</div>
|
||
|
|
|
||
|
|
<p>The Save to Application exit program enables an application program to
|
||
|
|
receive the save records that are generated by a save-to-save-file operation
|
||
|
|
using the <a href="QaneSava.htm">Save to Application</a> (QaneSava) API.</p>
|
||
|
|
|
||
|
|
<p>The API calls the exit program once to start the transfer sequence, multiple
|
||
|
|
times to transfer each block of save records, and once to end the transfer
|
||
|
|
sequence.</p>
|
||
|
|
|
||
|
|
<p>The API passes to the exit program the operation type, the save data, the
|
||
|
|
length of the save data, the qualified name of the user space and the format
|
||
|
|
name of the user space.</p>
|
||
|
|
|
||
|
|
<p>The exit program must return the number of save bytes read, 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 read and store the save records in the order
|
||
|
|
presented, without modification, for the objects to be successfully
|
||
|
|
restored.</p>
|
||
|
|
|
||
|
|
<br>
|
||
|
|
|
||
|
|
|
||
|
|
<h3>Authorities and Locks</h3>
|
||
|
|
|
||
|
|
<p>See <a href="QaneSava.htm">Save to Application</a> (QaneSava) 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 save 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 (copy, store, and so
|
||
|
|
forth) a block of save 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 save 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 save
|
||
|
|
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 save
|
||
|
|
operation before any save records are transferred.</p>
|
||
|
|
|
||
|
|
<p>Operation type 2 (transfer) is issued multiple times during the save
|
||
|
|
operation as each block of save records becomes available. The exit program
|
||
|
|
must read the entire block of save records.</p>
|
||
|
|
|
||
|
|
<p>Operation type 3 (end) is issued only once at the end of the save operation
|
||
|
|
after all save records are transferred.</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
|
||
|
|
save records transfer. These conditions are:</p>
|
||
|
|
|
||
|
|
<ul>
|
||
|
|
<li>The API detects an error with the system save 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>
|
||
|
|
</table>
|
||
|
|
|
||
|
|
<br>
|
||
|
|
</dd>
|
||
|
|
|
||
|
|
<dt><strong>Save data</strong></dt>
|
||
|
|
|
||
|
|
<dd>INPUT; CHAR(*)
|
||
|
|
|
||
|
|
<p>A block of save records. This parameter is passed only on operation type 2
|
||
|
|
(transfer).</p>
|
||
|
|
</dd>
|
||
|
|
|
||
|
|
<dt><strong>Length of save 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 the block of save
|
||
|
|
records. <!-- Begin V5R2 change - SPH - 10/08/2001 -->
|
||
|
|
The value for this parameter
|
||
|
|
currently is 1 048 832 bytes for all but the last operation, which
|
||
|
|
may be less.
|
||
|
|
<!-- End V5R2 change - SPH - 08/20/2001 --></p>
|
||
|
|
</dd>
|
||
|
|
|
||
|
|
<dt><strong>Save bytes read</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), the exit program must return a value that
|
||
|
|
indicates the number of save record bytes successfully read. The API abnormally
|
||
|
|
ends the transfer sequence if the returned value does not equal the length of
|
||
|
|
save data.</p>
|
||
|
|
</dd>
|
||
|
|
|
||
|
|
<dt><strong>Qualified user space name</strong></dt>
|
||
|
|
|
||
|
|
<dd>INPUT; CHAR(20)
|
||
|
|
|
||
|
|
<p>The qualified user space name specified by the application on the call to
|
||
|
|
the Save to Application (QaneSava) 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 Save to Application API. For the format of the structure, see the
|
||
|
|
SVRS0100 Format in the <a href="QaneSava.htm">Save to Application</a>
|
||
|
|
(QaneSava) 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 prevent 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>
|
||
|
|
|