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

755 lines
20 KiB
HTML
Raw Permalink 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>Qp0lSaveStgFree()--Save Storage Free</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. -->
<!-- Change History: -->
<!-- YYMMDD USERID Change description -->
<!-- BACKMST SCRIPT A converted by B2H R4.1 (346) (CMS) by v2kea304 at -->
<!-- RCHVMW2 on 26 April 1999 at 10:21:58 -->
<!-- 020618 EMIG: updated for NFS threadsafety, V5R3 -->
<!-- 020718 MFENLON: updated for QFileSvr.400 threadsafety, V5R3 -->
<!-- 020918 Rosckes: Add ENOTAVAIL errno descritpion, V5R3 -->
<!-- 040225 TIMCLARK: Add usage note for virtual volumes, V5R4 -->
<!-- 0201?? V2CDIJAB File cleanup completed -->
<!-- 050407 JTROUS: fix enums, no change flag, V5R4 -->
<!-- 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>Qp0lSaveStgFree()--Save Storage Free</h2>
<div class="box" style="width: 80%;">
<br>
&nbsp;&nbsp;Syntax<br>
<pre>
#include &lt;Qp0lstdi.h&gt;
int Qp0lSaveStgFree(
Qlg_Path_Name_T *<em>Path_Name</em>,
Qp0l_StgFree_Function_t *<em>UserFunction_ptr</em>,
void *<em>Function_CtlBlk_ptr</em>);
</pre>
&nbsp;&nbsp;Service Program Name: QP0LLIB3<br>
<!-- iddvc RMBR -->
<br>
&nbsp;&nbsp;Default Public Authority: *USE<br>
<!-- iddvc RMBR -->
<br>
&nbsp;&nbsp;Threadsafe: Conditional; see <a href="#usagenotes">Usage
Notes</a>.<br>
<!-- iddvc RMBR -->
<br>
</div>
<p>The <strong>Qp0lSaveStgFree()</strong> function calls a user-supplied exit
program to save i5/OS objects of type *STMF and, upon successful completion of
the exit program, frees the storage for the object and marks the object as
storage freed. The *STMF object and its attributes remain on the system, but
the storage occupied by the *STMF object's data is deleted. The *STMF object
cannot be used until it is restored to the system. This is accomplished by
either of the following:</p>
<ul>
<li>Restoring the object using the RST command.</li>
<li>Requesting an operation on the object, requiring one of the following,
which will dynamically retrieve (restore) the *STMF object:
<ul compact>
<li>Accessing the object's data (<strong>open()</strong>, <strong>
creat()</strong>, MOV, CPY, CPYFRMSTMF, or CPYTOSTMF).</li>
<li>Adding a new name to the object (RNM, ADDLNK, <strong>link()</strong>,
<strong>rename()</strong>, <strong>Qp0lRenameKeep()</strong>, or <strong>
Qp0lRenameUnlink()</strong>).</li>
<li>Checking out the object (CHKOUT).</li>
</ul>
</li>
</ul>
<p>The restore operation is done by calling a user-provided exit program
registered against the Storage Extension exit point QIBM_QTA_STOR_EX400.
For information on this exit point, see the <a href="XTASX400.htm">Storage
Extension Exit Program</a>.</p>
<p><strong>Qp0lSaveStgFree()</strong> returns EOFFLINE for an object that is
already storage freed or returns EBUSY for an object that is checked out.</p>
<p>The user exit program can be either a procedure or a program.</p>
<br>
<h3>Parameters</h3>
<dl>
<dt><strong><em>Path_Name</em></strong></dt>
<dd>(Input) A pointer to a path name whose last component is the object that is
saved and whose storage is freed. This path name is in the Qlg_Path_Name_T
format. For more information on this structure, see <a href="../apiref/pns.htm">Path name
format</a>.
<p>If the last component of the path name supplied on the call to <strong>
Qp0lSaveStgFree()</strong> is a symbolic link, then <strong>
Qp0lSaveStgFree()</strong> resolves and follows the link to its target and
performs its normal <strong>Qp0lSaveStgFree()</strong> functions on that
target. If the symbolic link refers to an object in a remote file system,
<strong>Qp0lSaveStgFree()</strong> returns ENOTSUP to the calling program.</p>
</dd>
<dt><strong><em>UserFunction_ptr</em></strong></dt>
<dd>(Input) A pointer to a structure that contains information about the user
exit program that the caller wants <strong>Qp0lSaveStgFree()</strong> to call
to save an *STMF object. This user exit program can be either a procedure or a
program. If this pointer is NULL, <strong>Qp0lSaveStgFree()</strong> does not
call an exit program to save the object but does free the object's storage and
marks it as storage freed.<br>
<br>
<table border width="80%">
<tr>
<th align="left" valign="bottom" colspan="4"><em>User Function
Pointer</em></th>
</tr>
<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%">Function type flag</td>
</tr>
<tr>
<td align="center" valign="top">14</td>
<td align="center" valign="top">E</td>
<td align="left" valign="top">CHAR(10)</td>
<td align="left" valign="top">Program library</td>
</tr>
<tr>
<td align="center" valign="top">4</td>
<td align="center" valign="top">4</td>
<td align="left" valign="top">CHAR(10)</td>
<td align="left" valign="top">Program name</td>
</tr>
<tr>
<td align="center" valign="top">24</td>
<td align="center" valign="top">18</td>
<td align="left" valign="top">CHAR(1)</td>
<td align="left" valign="top">Multithreaded job action</td>
</tr>
<tr>
<td align="center" valign="top">25</td>
<td align="center" valign="top">19</td>
<td align="left" valign="top">CHAR(7)</td>
<td align="left" valign="top">Reserved</td>
</tr>
<tr>
<td align="center" valign="top">32</td>
<td align="center" valign="top">20</td>
<td align="left" valign="top">PP(*)</td>
<td align="left" valign="top">Procedure pointer to exit procedure</td>
</tr>
</table>
<p><strong>Function type flag.</strong>&nbsp;&nbsp; A flag that indicates
whether the Save Storage Free exit program called by <strong>
Qp0lSaveStgFree()</strong> is a procedure or a program. If the exit program is
a procedure, this flag is set to 0, and the procedure pointer to exit procedure
field points to the procedure called by <strong>Qp0lSaveStgFree()</strong>. If
the exit program is a program, this flag is set to 1 and a program name and
program library are provided, respectively, in the program name and program
library fields. Valid values follow:</p>
<table cellpadding="5">
<!-- cols="5 95" -->
<tr>
<td align="left" valign="top"><em>0</em></td>
<td align="left" valign="top">QP0L_USER_FUNCTION_PTR: A user procedure is
called.</td>
</tr>
<tr>
<td align="left" valign="top"><em>1</em></td>
<td align="left" valign="top">QP0L_USER_FUNCTION_PGM: A user program is
called.</td>
</tr>
</table>
<p><strong>Multithreaded job action.</strong>&nbsp;&nbsp; (Input) A CHAR(1)
value that indicates the action to take in a multithreaded job. The default
value is QP0L_MLTTHDACN_SYSVAL. For release compatibility and for processing
this parameter against the QMLTTHDACN system value, x'00, x'01', x'02', &amp;
x'03' are treated as x'F0', x'F1', x'F2', and x'F3'.</p>
<table cellpadding="5">
<!-- cols="10 90" -->
<tr>
<td align="left" valign="top" width="10%"><em>x'00'</em></td>
<td align="left" valign="top" width="90%">QP0L_MLTTHDACN_SYSVAL: The API evaluates the
QMLTTHDACN system value to determine the action to take in a multithreaded job.
Valid QMLTTHDACN system values follow:
<table cellpadding="5">
<tr>
<td align="left" valign="top"><em>'1'</em></td>
<td align="left" valign="top">Call the exit program. Do not send an
informational message.</td>
</tr>
<tr>
<td align="left" valign="top"><em>'2'</em></td>
<td align="left" valign="top">Call the exit program and send informational
message CPI3C80.</td>
</tr>
<tr>
<td align="left" valign="top"><em>'3'</em></td>
<td align="left" valign="top">The exit program is not called when the API
determines that it is running in a multithreaded job. ENOTSAFE is
returned.</td>
</tr>
</table>
</td>
</tr>
<tr>
<td align="left" valign="top"><em>x'01'</em></td>
<td align="left" valign="top">QP0L_MLTTHDACN_NOMSG: Call the exit program. Do
not send an informational message.</td>
</tr>
<tr>
<td align="left" valign="top"><em>x'02'</em></td>
<td align="left" valign="top">QP0L_MLTTHDACN_MSG: Call the exit program and
send informational message CPI3C80.</td>
</tr>
<tr>
<td align="left" valign="top"><em>x'03'</em></td>
<td align="left" valign="top">QP0L_MLTTHDACN_NO: The exit program is not called
when the API determines that it is running in a multithreaded job. ENOTSAFE is
returned.</td>
</tr>
</table>
<p><strong>Procedure pointer to exit procedure.</strong>&nbsp;&nbsp; If the
function type flag is 0, which indicates that a procedure is called instead of
a program, this field contains a procedure pointer to the procedure that
<strong>Qp0lSaveStgFree()</strong> calls. This field must be NULL if the
function type flag is 1.</p>
<p><strong>Program library.</strong>&nbsp;&nbsp; If the function type flag is
1, indicating a program is called, this field contains the library in which the
program being called (identified by the program name field) is located. This
field must be blank if the function type flag is 0.</p>
<p><strong>Program name.</strong>&nbsp;&nbsp; If the function type flag is 1,
indicating a program is called, this field contains the name of the program
that is called. The program should be located in the library identified by the
program library field. This field must be blank if the function type flag is
0.</p>
<p><strong>Reserved.</strong>&nbsp;&nbsp; A reserved field. This field must be
set to binary zero.</p>
</dd>
<dt><strong><em>Function_CtlBlk_ptr</em></strong></dt>
<dd>(Input) A pointer to any data that the caller of <strong>
Qp0lSaveStgFree()</strong> wants to have passed to the user-defined Save
Storage Free exit program that <strong>Qp0lSaveStgFree()</strong> calls to save
an *STMF object. <strong>Qp0lSaveStgFree()</strong> does not process the data
that is referred to by this pointer. The API passes this pointer as a parameter
to the user-defined Save Storage Free exit program that was specified on its
call. This is a means for the caller of <strong>Qp0lSaveStgFree()</strong> to
pass information to and from the Save Storage Free exit program.</dd>
</dl>
<br>
<h3>Authorities</h3>
<p>The following table shows the authorization required for the
Qp0lSaveStgFree() API.</p>
<table border="1">
<tr>
<th align="left" valign="bottom">Object Referred to</th>
<th align="center" valign="bottom">Authority Required</th>
<th align="center" valign="bottom">errno</th>
</tr>
<tr>
<td align="left" valign="top" width="65%">Each directory, preceding the last
component, in a <em>path name</em></td>
<td align="center" valign="top" width="20%">*RX</td>
<td align="center" valign="top" width="15%">EACCES</td>
</tr>
<tr>
<td align="left" valign="top">Object</td>
<td align="center" valign="top">*SAVSYS or *RW</td>
<td align="center" valign="top">EACCES</td>
</tr>
<tr>
<td align="left" valign="top">Any called program pointed to by the <em>
UserFunction_ptr</em> parameter</td>
<td align="center" valign="top">*X</td>
<td align="center" valign="top">EACCES</td>
</tr>
<tr>
<td align="left" valign="top">Any library containing the called program pointed
to by the <em>UserFunction_ptr</em> parameter</td>
<td align="center" valign="top">*X</td>
<td align="center" valign="top">EACCES</td>
</tr>
</table>
<br>
<br>
<h3>Return Value</h3>
<table cellpadding="5">
<!-- cols="5 95" -->
<tr>
<td align="left" valign="top"><em>0</em></td>
<td align="left" valign="top"><strong>Qp0lSaveStgFree()</strong> was
successful.</td>
</tr>
<tr>
<td align="left" valign="top"><em>-1</em></td>
<td align="left" valign="top"><strong>Qp0lSaveStgFree()</strong> was not
successful. The <em>errno</em> global variable is set to indicate the
error.</td>
</tr>
</table>
<br>
<br>
<h3>Error Conditions</h3>
<p>If <strong>Qp0lSaveStgFree()</strong> is not successful, <em>errno</em>
indicates one of the following errors:</p>
<table cellpadding="5">
<!-- cols="25 75" -->
<tr>
<th align="left" valign="bottom">Error condition</th>
<th align="left" valign="bottom">Additional information</th>
</tr>
<tr>
<td align="left" valign="top">
<em>[<a href="unix14.htm#EACCES">EACCES</a>]</em></td>
<td align="left" valign="top">
<p>If you are accessing a remote file through the Network File System, update
operations to file permissions at the server are not reflected at the client
until updates to data that is stored locally by the Network File System take
place. (Several options on the Add Mounted File System (ADDMFS) command
determine the time between refresh operations of local data.) Access to a
remote file may also fail due to different mappings of user IDs (UID) or group
IDs (GID) on the local and remote systems.</p>
</td>
</tr>
<tr>
<td align="left" valign="top">
<em>[<a href="unix14.htm#EAGAIN">EAGAIN</a>]</em></td>
<td align="left" valign="top">
&nbsp;
</td>
</tr>
<tr>
<td align="left" valign="top">
<em>[<a href="unix14.htm#EBADNAME">EBADNAME</a>]</em></td>
<td align="left" valign="top">
&nbsp;
</td>
</tr>
<tr>
<td align="left" valign="top">
<em>[<a href="unix14.htm#EBUSY">EBUSY</a>]</em></td>
<td align="left" valign="top">
&nbsp;
</td>
</tr>
<tr>
<td align="left" valign="top">
<em>[<a href="unix14.htm#EDAMAGE">EDAMAGE</a>]</em></td>
<td align="left" valign="top">
&nbsp;
</td>
</tr>
<tr>
<td align="left" valign="top">
<em>[<a href="unix14.htm#EFAULT">EFAULT</a>]</em></td>
<td align="left" valign="top">
&nbsp;
</td>
</tr>
<tr>
<td align="left" valign="top">
<em>[<a href="unix14.htm#EINVAL">EINVAL</a>]</em></td>
<td align="left" valign="top">
&nbsp;
</td>
</tr>
<tr>
<td align="left" valign="top">
<em>[<a href="unix14.htm#EIO">EIO</a>]</em></td>
<td align="left" valign="top">
&nbsp;
</td>
</tr>
<tr>
<td align="left" valign="top">
<em>[<a href="unix14.htm#EISDIR">EISDIR</a>]</em></td>
<td align="left" valign="top">
&nbsp;
</td>
</tr>
<tr>
<td align="left" valign="top">
<em>[<a href="unix14.htm#ELOOP">ELOOP</a>]</em></td>
<td align="left" valign="top">
&nbsp;
</td>
</tr>
<tr>
<td align="left" valign="top">
<em>[<a href="unix14.htm#EMFILE">EMFILE</a>]</em></td>
<td align="left" valign="top">
&nbsp;
</td>
</tr>
<tr>
<td align="left" valign="top">
<em>[<a href="unix14.htm#ENAMETOOLONG">ENAMETOOLONG</a>]</em></td>
<td align="left" valign="top">
&nbsp;
</td>
</tr>
<tr>
<td align="left" valign="top">
<em>[<a href="unix14.htm#ENFILE">ENFILE</a>]</em></td>
<td align="left" valign="top">
&nbsp;
</td>
</tr>
<tr>
<td align="left" valign="top">
<em>[<a href="unix14.htm#ENOENT">ENOENT</a>]</em></td>
<td align="left" valign="top">
&nbsp;
</td>
</tr>
<tr>
<td align="left" valign="top">
<em>[<a href="unix14.htm#ENOMEM">ENOMEM</a>]</em></td>
<td align="left" valign="top">
&nbsp;
</td>
</tr>
<tr>
<td align="left" valign="top">
<em>[<a href="unix14.htm#ENOTAVAIL">ENOTAVAIL</a>]</em></td>
<td align="left" valign="top">
&nbsp;
</td>
</tr>
<tr>
<td align="left" valign="top">
<em>[<a href="unix14.htm#ENOTDIR">ENOTDIR</a>]</em></td>
<td align="left" valign="top">
&nbsp;
</td>
</tr>
<tr>
<td align="left" valign="top">
<em>[<a href="unix14.htm#ENOSPC">ENOSPC</a>]</em></td>
<td align="left" valign="top">
&nbsp;
</td>
</tr>
<tr>
<td align="left" valign="top">
<em>[<a href="unix14.htm#ENOSYSRSC">ENOSYSRSC</a>]</em></td>
<td align="left" valign="top">
&nbsp;
</td>
</tr>
<tr>
<td align="left" valign="top">
<em>[<a href="unix14.htm#ENOTSAFE">ENOTSAFE</a>]</em></td>
<td align="left" valign="top">
&nbsp;
</td>
</tr>
<tr>
<td align="left" valign="top">
<em>[<a href="unix14.htm#ENOTSUP">ENOTSUP</a>]</em></td>
<td align="left" valign="top">
&nbsp;
</td>
</tr>
<tr>
<td align="left" valign="top">
<em>[<a href="unix14.htm#EOFFLINE">EOFFLINE</a>]</em></td>
<td align="left" valign="top">
&nbsp;
</td>
</tr>
<tr>
<td align="left" valign="top">
<em>[<a href="unix14.htm#EUNKNOWN">EUNKNOWN</a>]</em></td>
<td align="left" valign="top">
&nbsp;
</td>
</tr>
</table>
<br>
<h3>Error Messages</h3>
<p>The following messages may be sent from this function:</p>
<table width="100%" cellpadding="5">
<tr>
<th align="left" valign="top" nowrap>Message ID</th>
<th align="left" valign="top">Error Message Text</th>
</tr>
<tr>
<td align="left" valign="top" width="15%">CPI3C80 I</td>
<td align="left" valign="top" width="85%">An exit program has been called for
which the threadsafety status was not known.</td>
</tr>
<tr>
<td align="left" valign="top">CPFA0D4 E</td>
<td align="left" valign="top">File system error occurred.</td>
</tr>
<tr>
<td align="left" valign="top">CPE3418 E</td>
<td align="left" valign="top">Possible APAR condition or hardware failure.</td>
</tr>
<tr>
<td align="left" valign="top">CPF3CF2 E</td>
<td align="left" valign="top">Error(s) occurred during running of &amp;1
API.</td>
</tr>
<tr>
<td align="left" valign="top">CPF9872 E</td>
<td align="left" valign="top">Program or service program &amp;1 in library
&amp;2 ended. Reason code &amp;3.</td>
</tr>
</table>
<br>
<br>
<h3><a name="usagenotes">Usage Notes</a></h3>
<ul>
<li>This function will fail with error code [ENOTSAFE] when both of the
following conditions occur:<br>
<br>
<ul>
<li>Where multiple threads exist in the job.<br>
<br>
</li>
<li>The object this function is operating on resides in a file system that is
not threadsafe. Only the following file systems are threadsafe for this
function:<br>
<br>
<ul>
<li>"Root" (/)</li>
<li>QOpenSys</li>
<li>User-defined</li>
<li>QNTC</li>
<li>QSYS.LIB</li>
<li>QOPT</li>
<li>Network File System</li>
<li>QFileSvr.400</li>
</ul>
</li>
</ul>
<br>
</li>
<li>If the Save Storage Free exit program calls the SAV command or the <strong>
QsrSave</strong> function or any other function that is not threadsafe, and
there are secondary threads active in the job, <strong>
Qp0lSaveStgFree()</strong> may fail as a result.<br>
<br>
</li>
<li>If the Save Storage Free exit program is not threadsafe or uses a function
that is not threadsafe, then <strong>Qp0lSaveStgFree()</strong> is not
threadsafe.<br>
<br>
</li>
<li><img src="delta.gif" alt="Start of change">
This function will fail with error code [EINVAL] if the stream file this
function is operating on is a virtual volume.
<img src="deltaend.gif" alt="End of change">
</li>
</ul>
<br>
<h3>Related Information</h3>
<ul>
<li>The &lt;<strong>Qp0lstdi.h</strong>&gt; file
</li>
<li><a href="qsavstgfu.htm">QlgSaveStgFree()</a>--Save Storage Free (using
NLS-enabled path name)</li>
<li><a href="XSAVSTGF.htm">Save Storage Free Exit Program</a></li>
</ul>
<br>
<h3>Example</h3>
<p>See <a href="../apiref/aboutapis.htm#codedisclaimer">Code disclaimer information</a>
for information pertaining to code examples.</p>
<p>See <strong><a href="qgetattr.htm">Qp0lGetAttr()</a></strong>
description for a code example that shows
a call to <strong>Qp0lSaveStgFree()</strong> by using a procedure as the exit
program. This API also shows an example of a call to <strong>
Qp0lGetAttr()</strong>.</p>
<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="unix.htm">UNIX-Type 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