559 lines
18 KiB
HTML
559 lines
18 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>Storage Extension 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 -->
|
|
<!-- File tagging validation 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>Storage Extension Exit Program</h2>
|
|
|
|
<div class="box" style="width: 65%;">
|
|
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%">Object description information</td>
|
|
<td align="left" valign="top" width="20%">Input</td>
|
|
<td align="left" valign="top" width="20%">Char(*)</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td align="center" valign="top">2</td>
|
|
<td align="left" valign="top">Control value information</td>
|
|
<td align="left" valign="top">Output</td>
|
|
<td align="left" valign="top">Char(*)</td>
|
|
</tr>
|
|
</table>
|
|
|
|
<br>
|
|
QSYSINC Member Name: ETASTGEX<br>
|
|
<!-- iddvc RMBR -->
|
|
<br>
|
|
Exit Point Name: QIBM_QTA_STOR_EX400<br>
|
|
<!-- iddvc RMBR -->
|
|
<br>
|
|
Exit Point Format Name: EX400200, EX400300<br>
|
|
<!-- iddvc RMBR -->
|
|
<br>
|
|
</div>
|
|
|
|
<p>The Storage Extension exit program provides the capability of restoring the
|
|
entire object using a storage extension, that is, restoring objects that were
|
|
saved using *FREE, or freed through an application programming interface. (*DOC
|
|
and *STMF files are freed through an API, not through save using *FREE.)</p>
|
|
|
|
<p><strong>Note:</strong> To use this exit program, you need the Media and
|
|
Storage Extension feature of the i5/OS.</p>
|
|
|
|
<p>If there is any program registered against exit point format name EX400200
|
|
of this exit point, then any programs registered against exit point format name
|
|
EX400300 will not be called. Therefore, if you are installing your application
|
|
and you are registering it against exit point format EX400300, verify that no
|
|
programs are registered against exit point format name EX400200. If there are
|
|
any, notify the user that it needs to be disabled before the application will
|
|
work. Do not simply deregister programs from exit point format name EX400200
|
|
when installing your application because it may impact other applications.</p>
|
|
|
|
<p><strong>Storage extension</strong> refers to those objects (and the CL
|
|
commands that refer to those objects) saved from disk using the *FREE option on
|
|
the storage parameter. These saved objects free disk space by storing a copy of
|
|
the entire object and keeping only the object headers on disk. Currently, only
|
|
file, document, and stream objects are supported.</p>
|
|
|
|
<br>
|
|
|
|
|
|
<h3>Exit Point Format EX400200</h3>
|
|
|
|
<p>Objects may be scheduled to be saved from disk when they are not referred to
|
|
for a specified amount of time. When the objects are saved, the object data is
|
|
saved and the object headers remain on disk. When this object is referred to,
|
|
the operating system calls the exit program for object restoration through the
|
|
registration facility. (For information about registering an exit point with
|
|
the registration facility and adding an exit program to an exit point, <a href=
|
|
"reg1.htm">Registration Facility APIs</a>. The exit point format EX400200
|
|
supports only one exit program.)</p>
|
|
|
|
<p>When the user exit program is given control, it verifies that the object was
|
|
saved. If the exit program has the object saved and wants to restore it, the
|
|
exit program restores the object data and returns a control value to the i5/OS
|
|
operating system indicating that the object was restored through the control
|
|
value information. If the exit program does not have the object saved, it
|
|
returns a control value to i5/OS indicating that the object was not restored
|
|
through the control value information.</p>
|
|
|
|
<br>
|
|
|
|
|
|
<h3>Exit Point Format EX400300</h3>
|
|
|
|
<p>When an object is determined to be saved using *FREE, each program that is
|
|
registered against exit point format name EX400300 will be called (as long as
|
|
no programs are registered against EX400200) with an indicator that it is
|
|
asking for a date/time stamp of the most recent version of the object that the
|
|
exit program has.</p>
|
|
|
|
<p>After all programs are called, the exit program that specified the most
|
|
recent date/time stamp will be called again with the indicator to restore the
|
|
object.</p>
|
|
|
|
<p>After the user exit program is given control and restores the object that
|
|
was suspended, it should return the control value to the i5/OS operating
|
|
system indicating that the object was restored through the control value
|
|
information.</p>
|
|
|
|
<br>
|
|
|
|
|
|
<!-- Please NOTE: DO NOT DELETE THIS SECTION if this API has no authorities and locks. -->
|
|
<!-- Instead, use the commented out coding below to indicate NONE. -->
|
|
<h3>Authorities and Locks</h3>
|
|
|
|
<!-- Use this if there are no authorities and locks. -->
|
|
<p>None.</p>
|
|
|
|
<br>
|
|
<h3>Required Parameter Group</h3>
|
|
|
|
<dl>
|
|
<dt><strong>Object description information</strong></dt>
|
|
|
|
<dd>INPUT; CHAR(*)
|
|
|
|
<p>Information about the object that the exit program will attempt to restore
|
|
from storage extension. For details, see <a href="#HDRODIF">Format of Object
|
|
Description Information (EX400200,EX400300)</a>.</p>
|
|
</dd>
|
|
|
|
<dt><strong>Control value information</strong></dt>
|
|
|
|
<dd>OUTPUT; CHAR(*)
|
|
|
|
<p>Information about whether the exit program restored the object requested or
|
|
did not have the object stored in storage extension. For details, see <a href=
|
|
"#HDRCVIF">Format of Control Value Information</a>.</p>
|
|
</dd>
|
|
</dl>
|
|
|
|
<br>
|
|
|
|
|
|
<h3><a name="HDRODIF">Format of Object Description Information
|
|
(EX400200,EX400300)</a></h3>
|
|
|
|
<p>The following table shows the format of the object description information.
|
|
For a description of the fields in this format, see <a href="#HDRODIFF">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">BINARY(4)</td>
|
|
<td align="left" valign="top" width="60%">Length of object description
|
|
information</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">Length of control value information</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td align="center" valign="top">8</td>
|
|
<td align="center" valign="top">8</td>
|
|
<td align="left" valign="top">CHAR(10)</td>
|
|
<td align="left" valign="top">Object name</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td align="center" valign="top">18</td>
|
|
<td align="center" valign="top">12</td>
|
|
<td align="left" valign="top">CHAR(10)</td>
|
|
<td align="left" valign="top">Object library name</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td align="center" valign="top">28</td>
|
|
<td align="center" valign="top">1C</td>
|
|
<td align="left" valign="top">CHAR(10)</td>
|
|
<td align="left" valign="top">Object type</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td align="center" valign="top">38</td>
|
|
<td align="center" valign="top">26</td>
|
|
<td align="left" valign="top">CHAR(10)</td>
|
|
<td align="left" valign="top">Member name</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td align="center" valign="top">48</td>
|
|
<td align="center" valign="top">30</td>
|
|
<td align="left" valign="top">CHAR(10)</td>
|
|
<td align="left" valign="top">Job name</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td align="center" valign="top">58</td>
|
|
<td align="center" valign="top">3A</td>
|
|
<td align="left" valign="top">CHAR(10)</td>
|
|
<td align="left" valign="top">User name</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td align="center" valign="top">68</td>
|
|
<td align="center" valign="top">44</td>
|
|
<td align="left" valign="top">CHAR(6)</td>
|
|
<td align="left" valign="top">Job number</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td align="center" valign="top">74</td>
|
|
<td align="center" valign="top">4A</td>
|
|
<td align="left" valign="top">CHAR(2)</td>
|
|
<td align="left" valign="top">Reserved</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td align="center" valign="top">76</td>
|
|
<td align="center" valign="top">4C</td>
|
|
<td align="left" valign="top">BINARY(4)</td>
|
|
<td align="left" valign="top">Offset to path name structure</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td align="center" valign="top">80</td>
|
|
<td align="center" valign="top">50</td>
|
|
<td align="left" valign="top">BINARY(4)</td>
|
|
<td align="left" valign="top">Length of path name structure</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td align="center" valign="top">84</td>
|
|
<td align="center" valign="top">54</td>
|
|
<td align="left" valign="top">CHAR(10)</td>
|
|
<td align="left" valign="top">Request type</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td align="center" valign="top">94</td>
|
|
<td align="center" valign="top">5E</td>
|
|
<td align="left" valign="top">CHAR(13)</td>
|
|
<td align="left" valign="top">Date/time stamp</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td align="center" valign="top"> </td>
|
|
<td align="center" valign="top"> </td>
|
|
<td align="left" valign="top">CHAR(*)</td>
|
|
<td align="left" valign="top">Path name structure</td>
|
|
</tr>
|
|
</table>
|
|
|
|
<br>
|
|
<br>
|
|
|
|
|
|
<h3><a name="HDRODIFF">Field Descriptions</a></h3>
|
|
|
|
<p><strong>Date/time stamp.</strong> The most recent date/time stamp that the
|
|
other exit programs have specified as their most recent copy of the suspended
|
|
object. If this is the first exit program being called, or no other exit
|
|
program has a copy of the suspended object to be restored, then this field will
|
|
be set to blanks. This field will be blanks when passed for exit format
|
|
EX400200. This field will be of the following CYYMMDDHHMMSS format:</p>
|
|
|
|
<table cellpadding="5">
|
|
<!-- cols="15 85" -->
|
|
<tr>
|
|
<td align="left" valign="top"><em>C</em></td>
|
|
<td align="left" valign="top">Century, where 0 indicates years 19<em>xx</em>
|
|
and 1 indicates years 20<em>xx</em>.</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td align="left" valign="top"><em>YYMMDD</em></td>
|
|
<td align="left" valign="top">The date (year, month, day format).</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td align="left" valign="top"><em>HHMMSS</em></td>
|
|
<td align="left" valign="top">The time (hours, minutes, seconds format).</td>
|
|
</tr>
|
|
</table>
|
|
|
|
<p><strong>Job name.</strong> The job name.</p>
|
|
|
|
<p><strong>Job number.</strong> The job number associated with the job name and
|
|
user identifier.</p>
|
|
|
|
<p><strong>Length of control value information.</strong> The length, in bytes,
|
|
of the control value information.</p>
|
|
|
|
<p><strong>Length of the path name structure.</strong> The length, in bytes, of
|
|
the path name structure. This field will be set to zero if the object does not
|
|
have a path name structure passed.</p>
|
|
|
|
<p><strong>Length of object description information.</strong> The length, in
|
|
bytes, of the object description information.</p>
|
|
|
|
<p><strong>Member name.</strong> The member within the file that caused the
|
|
exception.</p>
|
|
|
|
<p><strong>Object library name.</strong> The library name of the object being
|
|
referred to. The special value is:</p>
|
|
|
|
<table cellpadding="5">
|
|
<!-- cols="15 85" -->
|
|
<tr>
|
|
<td align="left" valign="top"><em>*PATH</em></td>
|
|
<td align="left" valign="top">The path name structure will contain the object
|
|
information.</td>
|
|
</tr>
|
|
</table>
|
|
|
|
<p><strong>Object name.</strong> The name of the object that is being referred
|
|
to and that causes an exception. The user exit program checks if it has this
|
|
object saved to storage extension. The special value is:</p>
|
|
|
|
<table cellpadding="5">
|
|
<!-- cols="15 85" -->
|
|
<tr>
|
|
<td align="left" valign="top"><em>*PATH</em></td>
|
|
<td align="left" valign="top">The path name structure will contain the object
|
|
information.</td>
|
|
</tr>
|
|
</table>
|
|
|
|
<p><strong>Object type.</strong> The standard object types known to the system.
|
|
Currently, only the following object types are supported:</p>
|
|
|
|
<table cellpadding="5">
|
|
<!-- cols="15 85" -->
|
|
<tr>
|
|
<td align="left" valign="top"><em>*FILE</em></td>
|
|
<td align="left" valign="top">File object (object name and library fields will
|
|
contain object name information).</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td align="left" valign="top"><em>*DOC</em></td>
|
|
<td align="left" valign="top">Document object (path name structure will contain
|
|
object name information).</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td align="left" valign="top"><em>*STMF</em></td>
|
|
<td align="left" valign="top">Stream file object (path name structure will
|
|
contain object name information).</td>
|
|
</tr>
|
|
</table>
|
|
|
|
<p><strong>Offset to path name structure.</strong> The offset, in bytes, to the
|
|
path name structure that is passed containing object pathname and translation
|
|
information. This field will be set to zero if the object does not have an path
|
|
name structure.</p>
|
|
|
|
<p><strong>Path name structure.</strong> The path name structure and
|
|
translation information for the suspended object. The path name structure
|
|
contains information such as CCSID, country or region, and language. For more information
|
|
on this structure, see <a href="../apiref/pns.htm">Path Name Format</a>.</p>
|
|
|
|
<p><strong>Request type.</strong> The type of request to the exit program from
|
|
the operating system. This field will always be *RESTORE for exit format
|
|
EX400200. Possible values are:</p>
|
|
|
|
<table cellpadding="5">
|
|
<!-- cols="15 85" -->
|
|
<tr>
|
|
<td align="left" valign="top"><em>*RESTORE</em></td>
|
|
<td align="left" valign="top">The exit program is getting called to restore the
|
|
object.</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td align="left" valign="top"><em>*DATETIME</em></td>
|
|
<td align="left" valign="top">The exit program is getting called to return the
|
|
latest date/time stamp of the most recent save operation of the suspended
|
|
object. Note that i5/OS does not restrict the called exit program from
|
|
actually restoring the object when called for a date/time stamp, but it will
|
|
only be a degradation in performance due to an extra restore of the
|
|
object.</td>
|
|
</tr>
|
|
</table>
|
|
|
|
<p><strong>Reserved.</strong> An unused field.</p>
|
|
|
|
<p><strong>User name.</strong> The user identifier of the caller.</p>
|
|
|
|
<br>
|
|
|
|
|
|
<h3><a name="HDRCVIF">Format of Control Value Information</a></h3>
|
|
|
|
<p> The following table shows the format of the control value information. For
|
|
a description of the fields in this format, see <a href="#HDRCVIFF">Control
|
|
Value 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%">CHAR(1)</td>
|
|
<td align="left" valign="top" width="60%">Object restoration information</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td align="center" valign="top">1</td>
|
|
<td align="center" valign="top">1</td>
|
|
<td align="left" valign="top">CHAR(13)</td>
|
|
<td align="left" valign="top">Date/time stamp</td>
|
|
</tr>
|
|
</table>
|
|
|
|
<br>
|
|
<br>
|
|
|
|
|
|
<h3><a name="HDRCVIFF">Control Value Field Descriptions</a></h3>
|
|
|
|
<p><strong>Date/time stamp.</strong> This field should be set by the exit
|
|
program when the request type specified in the <a href="#HDRODIF">Format of
|
|
Object Description Information (EX400200,EX400300)</a> is *DATETIME. This field
|
|
is used by the operating system to determine which registered exit program will
|
|
be called again to restore the object. The field is only used when programs
|
|
registered under exit point format EX400300 are called. The determination is
|
|
based on which exit program indicates the most recent copy of the suspended
|
|
object. This field will be of the following CYYMMDDHHMMSS format:</p>
|
|
|
|
<table cellpadding="5">
|
|
<!-- cols="15 85" -->
|
|
<tr>
|
|
<td align="left" valign="top"><em>C</em></td>
|
|
<td align="left" valign="top">Century, where 0 indicates years 19<em>xx</em>
|
|
and 1 indicates years 20<em>xx</em>.</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td align="left" valign="top"><em>YYMMDD</em></td>
|
|
<td align="left" valign="top">The date (year, month, day format).</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td align="left" valign="top"><em>HHMMSS</em></td>
|
|
<td align="left" valign="top">The time (hours, minutes, seconds format).</td>
|
|
</tr>
|
|
</table>
|
|
|
|
<p><strong>Object restoration information.</strong> Whether or not the object
|
|
was successfully restored or whether the exception should be resignaled. If
|
|
this field contains a value that is not valid, the value is ignored and message
|
|
CPD6705 is issued. The default for this field is 0. Valid 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 object has not been restored or was not asked
|
|
to be restored through the request type field.<br>
|
|
<strong>Note:</strong> This field should always be left by the exit program as
|
|
0 when the request type specified in the <a href="#HDRODIF">Format of Object
|
|
Description Information (EX400200,EX400300)</a> is *DATETIME.</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td align="left" valign="top"><em>1</em></td>
|
|
<td align="left" valign="top">The object has been restored.<br>
|
|
<strong>Note:</strong> If the user exit program specifies a 1 for this field
|
|
and it did not attempt to (or successfully) restore the entire object, message
|
|
CPD6704 is signaled.</td>
|
|
</tr>
|
|
</table>
|
|
|
|
<br>
|
|
<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%">CPD6704 D</td>
|
|
<td align="left" valign="top" width="85%">Error detected using program &1
|
|
in &2.</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td align="left" valign="top">CPD6705 D</td>
|
|
<td align="left" valign="top">Incorrect user exit control value specified.</td>
|
|
</tr>
|
|
</table>
|
|
|
|
<br>
|
|
|
|
|
|
<hr>
|
|
Exit program introduced: V3R1
|
|
|
|
<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="back1.htm">Backup and Recovery APIs</a> |
|
|
<a href="aplist.htm">APIs by category</a></td>
|
|
</tr>
|
|
</table>
|
|
</body>
|
|
</html>
|
|
|