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

1118 lines
46 KiB
HTML
Raw Normal View History

Add readme and dist folders
2024-04-02 14:02:31 +00:00
<!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>Integrated File System Scan on Close Exit Program</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 -->
<!-- JC1 SCRIPT A converted by B2H R4.1 (346) (CMS) by V2KEA304 -->
<!-- at RCHVMW2 on 17 Feb 1999 at 11:05:09 -->
<!-- 020308 JTROUS Crt Date, based on ifsopenexit.htm, V5R2, DCR 98680 -->
<!-- 021218 JTROUS Update to Usage notes etc(use v5r3a for BPs to see)-->
<!-- 030701 JTROUS Add EDEADLK usage note(due to scan mutex), v5r3a-->
<!-- 030723 JTROUS Add more words on CCSIDs, no change flag -->
<!-- 030805 JTROUS Add Kerberos usage note, v5r3a -->
<!-- 030812 JTROUS Fix select discussion on what will happen, v5r3a-->
<!-- 040212 JTROUS Fix socketpair doc,match late ENOTSUP, v5r4 -->
<!-- 040302 JTROUS Add O_FORCE_SCAN note, v5r4 -->
<!-- 040225 TIMCLARK Document restriction on virtual volumes, v5r4 -->
<!-- 040614 TIMCLARK Add poll() restriction, v5r4 -->
<!-- 040721 JTROUS Fix iSeries mentions, no change flag, V5r4 -->
<!-- 050119 JTROUS Fix wording on type1 restriction, V5r4 -->
<!-- 050316 JTROUS Add recvmsg to ENOTSUP list, V5r4 -->
<!-- 050415 JTROUS V5r4 API review updated, no change flag -->
<link rel="stylesheet" type="text/css" href="../rzahg/ic.css">
</head>
<body>
<!--End Header Records -->
<!-- Java sync-link -->
<script type="text/javascript" language="Javascript" src="../rzahg/synch.js">
</script>
<a name="Top_Of_Page"></a>
<h2>Integrated File System Scan on Close Exit Program</h2>
<div class="box" style="width: 80%;">
<br>
&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%">Integrated file system close exit
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">Status information</td>
<td align="left" valign="top">Output</td>
<td align="left" valign="top">Char(*)</td>
</tr>
</table>
<br>
&nbsp;&nbsp;QSYSINC Member Name: QP0LSCAN<br>
<!-- iddvc RMBR -->
<br>
&nbsp;&nbsp;Exit Point Name: QIBM_QP0L_SCAN_CLOSE<br>
<!-- iddvc RMBR -->
<br>
&nbsp;&nbsp;Exit Point Format Name: SCCL0100<br>
<!-- iddvc RMBR -->
<br>
</div>
<p>The integrated file system scan on close exit program is called to do scan
processing when an integrated file system object
is closed under the following conditions.</p>
<p>The exit program will <strong>not</strong> be called if:</p>
<ul>
<li>No exit programs exist for this exit point.</li>
<li>-or- the Scan file systems (QSCANFS) system value has
*NONE specified so that no file systems will be scanned.</li>
<li>-or- the object was marked to not be scanned
and a scan is not required because the object
was restored.
<img src="delta.gif" alt="Start of change">
(See <strong>Note</strong> 2)
<img src="deltaend.gif" alt="End of change"></li>
<li>-or- the object being closed was opened for write access only.</li>
<li>-or- <img src="delta.gif" alt="Start of change">
the object is being used as a network server
storage space or as a virtual volume. From the perspective of the server,
these objects appear as byte stream files within the integrated file system.
<img src="deltaend.gif" alt="End of change"></li>
<li>-or- the object is not being accessed from a file server, and the
Scan file systems control (QSCANFSCTL) system value has
*FSVRONLY specified so that only file server accesses are scanned.
<img src="delta.gif" alt="Start of change">
(See <strong>Note</strong> 2)
<img src="deltaend.gif" alt="End of change"></li>
<li>-or- the object is in a
<img src="delta.gif" alt="Start of change">
file system that has not completely converted to the *TYPE2 directory format.
For information on the *TYPE2 directory format, see the <a href=
"../cl/cvtdir.htm">Convert Directory (CVTDIR) command</a> and the
<a href="../ifs/rzaaxkickoff.htm">Integrated file system</a> information
in the Files and file systems topic.</td>
<img src="deltaend.gif" alt="End of change">
</li>
</ul>
<p>If the previous conditions have been met,
the exit program will be called if:</p>
<ul>
<li>The object has never been scanned.</li>
<li>-or- the object's data has been modified since the last time it was scanned.
Data modifications include writes, memory map writes, truncates or clears.</li>
<li>-or- the CCSID of the object has been modified since the last time
it was scanned.</li>
<li>-or- the To CCSID specified on the open request associated with this close
is different than the
last two To CCSIDs that were specified and previously scanned for this object.</li>
<li>-or- the object was opened in binary in association
with this close request, and it has not previously been
scanned in binary.</li>
<li>-or- there have been updates to the scanning software
and the object was not marked to be scanned only if the object changed.
<img src="delta.gif" alt="Start of change">
(See <strong>Note</strong> 2)
<img src="deltaend.gif" alt="End of change">
Updates to scanning software occur by either registering additional
exit programs for the scan-related exit points, or by calling
<a href="chgscansgn.htm">Change Scan Signature (QP0LCHSG) API</a> to
update the scan key signature associated with existing exit program scan keys. </li>
</ul>
<p><strong>Note:</strong> If there are multiple descriptors referencing the
same open instance of the object, then the exit program
will <strong>only</strong> be called for the close request on the last
descriptor.
Additionally, the From CCSID of the object will be the value it is at the point
in time of the close operation while the To CCSID will be reflective
of the value specified at open.
</p>
<p>For more information on close processing, see
<a href="close.htm">close()--Close File or Socket Descriptor</a>. For more information
on the scan-related attributes which can be set for objects,
see <A href="qsetattr.htm">Qp0lSetAttr()--Set Attributes.</a>
For more information on the
integrated file system scan processing and various options, see
the <a href="../ifs/rzaaxkickoff.htm">Integrated file system</a> information
in the Files and file systems topic.</p>
<p>The exit point supports a maximum of 50 exit programs. For
information about adding an exit program to an exit point, see the
<a href="reg1.htm">Registration Facility.</a></p>
<p><strong>Notes:</strong></p>
<ol>
<li>If the integrated file system exit program returns
any error messages or if any errors are received when attempting to call
the exit program,
the object will be treated as if the program was not called
and the object was not scanned. Therefore, the close operation will continue
unless the Scan file systems control (QSCANFSCTL) system value has
*ERRFAIL specified which will cause the operation to fail.
If a scan detects a failure, the close operation will still proceed and
complete to release the resources. If the Scan file systems
control (QSCANFSCTL) system value has *NOFAILCLO specified, the close operation
will not return any failure indication. If *NOFAILCLO is not specified,
the close operation will fail with error code [ESCANFAILURE].</li>
<!-- NOTE: The following list item must remain the second item -->
<!-- as other text says See Note #2. -->
<li><img src="delta.gif" alt="Start of change">
If the oflags specified when the object being closed was opened include the
O_FORCE_SCAN value, then one or more of the following conditions will be ignored when
determining whether the integrated file system scan-related exit programs
will be called:
<ul>
<li>The QSCANFSCTL system value specification of *FSVRONLY.
</li>
<li>The object was marked to not be scanned (e.g. scan attribute of *NO).
</li>
<li>The object was marked to be scanned only if the object changed
(e.g. scan attribute of *CHGONLY).
</li>
</ul>
For example, an object is closed that has a scan attribute of *YES,
and the close request is not through the file servers when
*FSVRONLY is specified. If O_FORCE_SCAN is specified on the open
request associated with this close request,
the object will be scanned if all the remaining conditions are met.
Similarly, if an object that has a scan attribute of *NO or
*CHGONLY is closed whose associated open request had O_FORCE_SCAN specified,
the object will be scanned if all the remaining conditions are met.
See <a href="open.htm#HDROPNFLAG">Using the oflag Parameter</a>
in <a href="open.htm">open()--Open File</a>
for more information on oflags.
<img src="deltaend.gif" alt="End of change">
</li>
</ol>
<br>
<h3>Restrictions</h3>
<ul>
<li>Only objects of type *STMF that are in
the "root" (/), QOpenSys, and user-defined file systems
<img src="delta.gif" alt="Start of change">
that have completely converted to the *TYPE2 directory format
<img src="deltaend.gif" alt="End of change">
are scanned.
For information on *TYPE2 directories, see
the <a href="../cl/cvtdir.htm">Convert Directory(CVTDIR) command</a>
and the <a href="../ifs/rzaaxkickoff.htm">Integrated file system</a> information
in the Files and file systems topic.
</li>
<li>The exit programs will not be called during an IPL or the vary-on of
an independent Auxiliary Storage Pool (ASP).</li>
<li>The exit programs will not be called when objects are being closed as a part
of a process end request.</li>
<li>During the call to the exit
programs, the ASP group associated with the thread will not be able to be changed.
</li>
<li>The exit programs must exist in the system ASP or
in a basic user ASP. They cannot exist in an independent ASP. Any ASP group could
be associated with the thread when the exit program is called. If the exit program
is not found, the object will be treated as if the program was not called
and the object was not scanned. Therefore, the close operation will continue
unless the Scan file systems control (QSCANFSCTL) system value has
*ERRFAIL specified which will cause the operation to fail.
If the Scan file systems
control (QSCANFSCTL) system value has *NOFAILCLO specified, the close operation
will not return any failure indication. If *NOFAILCLO is not specified,
the close operation will fail with error code [ESCANFAILURE].
</li>
<li>The exit programs could be called from an exit point within a
multi-threaded job and must be written to be threadsafe.</li>
</ul>
<br>
<h3>Authorities and Locks</h3>
<dl>
<dt><strong>User Profile Authority</strong></dt>
<dd>*ALLOBJ (all object) and *SECADM (security administrator) special authorities to add exit programs to the registration facility</dd>
<dd>*ALLOBJ and *SECADM special authorities to remove exit programs from the registration facility</dd>
</dl>
<br>
<h3>Program Data</h3>
<p>When you register the exit program, the following program data must be
provided. The following table shows the structure of the program data information.
For a description of the fields in this format, see <a href="#HDRSCCLFD">Field
Descriptions</a>.
This structure is defined in header file qp0lscan.h as data type
Qp0l_Scan_Program_Data_t.
</p>
<table border cellpadding="3">
<!-- cols="10 10 20 40" -->
<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">0</td>
<td align="center" valign="top">0</td>
<td align="left" valign="top">Char(10)</td>
<td align="left" valign="top">User profile</td>
</tr>
<tr>
<td align="center" valign="top">10</td>
<td align="center" valign="top">A</td>
<td align="left" valign="top">Char(20)</td>
<td align="left" valign="top">Scan key</td>
</tr>
<tr>
<td align="center" valign="top">30</td>
<td align="center" valign="top">1E</td>
<td align="left" valign="top">Char(12)</td>
<td align="left" valign="top">Scan key signature</td>
</tr>
</table>
<br>
<h3>Required Parameter Group</h3>
<dl>
<dt>Integrated file system close exit information</dt>
<dd>INPUT; CHAR(*)
<p>Information that is needed by the exit program to do its object scan
processing. For details, see <a href="#HDRSCCLFMT1">Format of
Integrated File System Close Exit Information</a>.
</p>
</dd>
<dt>Status information</dt>
<dd>OUTPUT; CHAR(*)
<p>Information that is returned by the exit program indicating what scan
processing has occurred. For details, see <a href="#HDRSCCLFMT2">Format of
Status Information</a>.</p>
</dd>
</dl>
<br>
<h3><a name="HDRSCCLFMT1">Format of Integrated File System Close Exit
Information (Input)</a></h3>
<p>The following table shows the structure of the integrated file system close exit
information for exit point format SCCL0100. For a description of the fields in
this format, see <a href="#HDRSCCLFD">Field Descriptions</a>.
This structure is defined in header file qp0lscan.h as data type
Qp0l_Scan_Exit_Information_t.
</p>
<table border cellpadding="3">
<!-- cols="10 10 20 40" -->
<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">0</td>
<td align="center" valign="top">0</td>
<td align="left" valign="top">BINARY(4)</td>
<td align="left" valign="top">Integrated file system close exit information
length</td>
</tr>
<tr>
<td align="center" valign="top">4</td>
<td align="center" valign="top">4</td>
<td align="left" valign="top">CHAR(20)</td>
<td align="left" valign="top">Exit point name</td>
</tr>
<tr>
<td align="center" valign="top">24</td>
<td align="center" valign="top">18</td>
<td align="left" valign="top">CHAR(8)</td>
<td align="left" valign="top">Exit point format name</td>
</tr>
<tr>
<td align="center" valign="top">32</td>
<td align="center" valign="top">20</td>
<td align="left" valign="top">BINARY(4)</td>
<td align="left" valign="top">Length of status information</td>
</tr>
<tr>
<td align="center" valign="top">32</td>
<td align="center" valign="top">20</td>
<td align="left" valign="top">BINARY(4)</td>
<td align="left" valign="top">Scan descriptor</td>
</tr>
<tr>
<td align="center" valign="top">36</td>
<td align="center" valign="top">24</td>
<td align="left" valign="top">BINARY(4), UNSIGNED</td>
<td align="left" valign="top">From CCSID</td>
</tr>
<tr>
<td align="center" valign="top">40</td>
<td align="center" valign="top">28</td>
<td align="left" valign="top">BINARY(4), UNSIGNED</td>
<td align="left" valign="top">To CCSID</td>
</tr>
<tr>
<td align="center" valign="top">44</td>
<td align="center" valign="top">2C</td>
<td align="left" valign="top">BINARY(4), UNSIGNED</td>
<td align="left" valign="top">Last failure CCSID</td>
</tr>
<tr>
<td align="center" valign="top">48</td>
<td align="center" valign="top">30</td>
<td align="left" valign="top">BINARY(4)</td>
<td align="left" valign="top">Oflags</td>
</tr>
<tr>
<td align="center" valign="top">52</td>
<td align="center" valign="top">34</td>
<td align="left" valign="top">CHAR(16)</td>
<td align="left" valign="top">File ID</td>
</tr>
<tr>
<td align="center" valign="top">68</td>
<td align="center" valign="top">44</td>
<td align="left" valign="top">CHAR(10)</td>
<td align="left" valign="top">Object type</td>
</tr>
<tr>
<td align="center" valign="top">78</td>
<td align="center" valign="top">4E</td>
<td align="left" valign="top">CHAR(1)</td>
<td align="left" valign="top">File system</td>
</tr>
<tr>
<td align="center" valign="top">79</td>
<td align="center" valign="top">4F</td>
<td align="left" valign="top">CHAR(1)</td>
<td align="left" valign="top">Additional call</td>
</tr>
<tr>
<td align="center" valign="top">80</td>
<td align="center" valign="top">50</td>
<td align="left" valign="top">CHAR(1)</td>
<td align="left" valign="top">Object modified since last scan</td>
</tr>
<tr>
<td align="center" valign="top">81</td>
<td align="center" valign="top">51</td>
<td align="left" valign="top">CHAR(1)</td>
<td align="left" valign="top">Scan signatures different</td>
</tr>
<tr>
<td align="center" valign="top">82</td>
<td align="center" valign="top">52</td>
<td align="left" valign="top">CHAR(1)</td>
<td align="left" valign="top">Call after previous failure</td>
</tr>
</table>
<br>
<h3><a name="HDRSCCLFMT2">Format of Status Information (Output)</a></h3>
<p>The following table shows the structure of the status information. For a
description of the fields in this format, see <a href="#HDRSCCLFD">Field
Descriptions</a>.
This structure is defined in header file qp0lscan.h as data type
Qp0l_Scan_Status_Information_t.
</p>
<table border cellpadding="3">
<!-- cols="10 10 20 40" -->
<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">0</td>
<td align="center" valign="top">0</td>
<td align="left" valign="top">BINARY(4)</td>
<td align="left" valign="top">Close scan status information length</td>
</tr>
<tr>
<td align="center" valign="top">4</td>
<td align="center" valign="top">4</td>
<td align="left" valign="top">BINARY(4), UNSIGNED</td>
<td align="left" valign="top">Failing CCSID</td>
</tr>
<tr>
<td align="center" valign="top">8</td>
<td align="center" valign="top">8</td>
<td align="left" valign="top">CHAR(1)</td>
<td align="left" valign="top">Update object scan information</td>
</tr>
<tr>
<td align="center" valign="top">9</td>
<td align="center" valign="top">9</td>
<td align="left" valign="top">CHAR(1)</td>
<td align="left" valign="top">Scan status</td>
</tr>
</table>
<br>
<h3><a name="HDRSCCLFD">Field Descriptions</a></h3>
<p><strong>Additional call.</strong>
Whether the exit program was called an additional time because another
<a href="ifscloseexit.htm">Integrated File System Scan on Close Exit Program</a>
that was called has indicated the object
was modified. See the <em>scan status</em> field for this modify indication.
The possible values are:</p>
<table cellpadding="5">
<!-- cols="30 70" -->
<tr>
<td valign="top"><em>QP0L_SCAN_CALL_FIRST (x'00')</em></td>
<td valign="top">The first call to the exit program.</td>
</tr>
<tr>
<td valign="top"><em>QP0L_SCAN_CALL_ADDL (x'01')</em></td>
<td valign="top">An additional call to the exit program
because another exit program has indicated the object was modified.</td>
</tr>
</table>
<p><strong>Call after previous failure.</strong>
Whether the exit program was called after the object had previously been
scanned and a failure detected.
The possible values are:</p>
<table cellpadding="5">
<!-- cols="25 75" -->
<tr>
<td valign="top"><em>QP0L_SCAN_NO (x'00')</em></td>
<td valign="top">This is not a call after a previous scan failure.
</td>
</tr>
<tr>
<td valign="top"><em>QP0L_SCAN_YES (x'01')</em></td>
<td valign="top">This is a call after a previous scan failure.
The <em>Last failure CCSID</em> field in conjunction with the
<em>From CCSID</EM> indicate the CCSID or binary indication of the failing
scan request.
<p><strong>Note:</strong> If the <em>Failing CCSID</em> and
<em>From CCSID</em> values match, it is the same as if the object
would have been opened in binary.</p>
</td>
</tr>
</table>
<p><strong>Close scan status information length.</strong>
The length in bytes of all data returned from the integrated file system close
exit program. The only valid value for this field is 10. If anything else is
specified, the object will be treated as if the program was not called
and the object was not scanned. Therefore, the close operation will continue
unless the Scan file systems control (QSCANFSCTL) system value has
*ERRFAIL specified which will cause the operation to fail.
If the Scan file systems
control (QSCANFSCTL) system value has *NOFAILCLO specified, the close operation
will not return any failure indication. If *NOFAILCLO is not specified,
the close operation will fail with error code [ESCANFAILURE].
</p>
<p><strong>Exit point format name.</strong>
The format name for the integrated
file system scan on close exit program. The possible format name follows:</p>
<table cellpadding="5">
<!-- cols="15 85" -->
<tr>
<td valign="top"><em>SCCL0100</em></td>
<td valign="top">The format name that is used while an object is being closed.</td>
</tr>
</table>
<p><strong>Exit point name.</strong>
The name of the exit point that is calling the exit program.</p>
<p><strong>Failing CCSID.</strong>
This field only has meaning if the <em>Call after previous failure</em>
field had a value of QP0L_SCAN_YES when the exit program was called, and if the
<em>Update object scan information</em> field has a value of QP0L_SCAN_YES,
and if the <em>Scan status</em> field has a value of QP0L_SCAN_FAILURE or
QP0L_SCAN_FAIL_WANT_MODIFY.
When the <em>Call after previous failure</em> had a value of QP0L_SCAN_YES,
then the scan exit program should verify that the object does not have any
problems when scanned using both the
<em>To CCSID</em> and <em>Last failure CCSID</em> values.
If either scan fails, then this field should be filled in with
the failing CCSID which will be stored as part of the object scan
information with the failure
indication. If the value of this field does not match either of the two input
CCSID fields, then the <em>To CCSID</em> value will be used.
If more than one exit program indicates a failure, the failing CCSID value which
will be preserved is from the last exit program which scanned the object and indicated
a failure.
For more information on CCSIDs and conversions,
see <a href="ifsopenexit.htm#HDRSCCSID">Coded Character Set Identifier (CCSID) Information</a> in
<a href="ifsopenexit.htm">Integrated File System Scan on Open Exit Program</a>.
</p>
<p><strong>Note:</strong> If the <em>Failing CCSID</em> and
<em>From CCSID</em> values match, it is the same as if the object
would have been opened in binary.</p>
<p><strong>File ID.</strong>
A unique identifier associated with the object that is being closed.
A file ID can be used with
<a href="getpthff.htm">Qp0lGetPathFromFileID()--Get Path Name
of Object from Its File ID</a>, to retrieve an object's path name.
</p>
<p><strong>File system.</strong>
The file system that the object being scanned is in.
The possible value follows:</p>
<table cellpadding="5">
<!-- cols="40 60" -->
<tr>
<td valign="top"><em>QP0L_SCAN_ROOT_QOPENSYS_UDFS (x'00')</em></td>
<td valign="top">The object is in the "root" (/), QOpenSys, or a
user-defined file system.</td>
</tr>
</table>
<p><strong>From CCSID.</strong>
The CCSID value that the data is in on the system itself
at the point in time of the close operation.
Therefore, this will be the CCSID in which data is to be returned
(when reading from the object using the <em>Scan descriptor</em>),
or the CCSID in which data is being supplied (when writing to the object
using the <em>Scan descriptor</em>).
For more information on CCSIDs and conversions,
see <a href="ifsopenexit.htm#HDRSCCSID">Coded Character Set Identifier (CCSID) Information</a> in
<a href="ifsopenexit.htm">Integrated File System Scan on Open Exit Program</a>.</p>
<p><strong>Integrated file system close exit information length.</strong>
The length in bytes of all data passed to the integrated file system close
exit program.</p>
<p><strong>Last failure CCSID.</strong>
The CCSID value that was specified when this object was
last scanned and indicated a scan failure.
This field only has meaning if the <em>Call after previous failure</em>
field has a value of QP0L_SCAN_YES.
Therefore, this would have
been the CCSID in which data was to have been returned (when the user
was to be reading from the object), or the CCSID in which data was to have
been supplied (when the user was to be writing to the object). However, that
request failed for this CCSID. This is now being returned so that this CCSID
can also be scanned, if it is different than the <em>To CCSID</em> value.
For more information on CCSIDs and conversions,
see <a href="ifsopenexit.htm#HDRSCCSID">Coded Character Set Identifier (CCSID) Information</a> in
<a href="ifsopenexit.htm">Integrated File System Scan on Open Exit Program</a>.</p>
<p><strong>Note:</strong> If the <em>Last failure CCSID</em> and
<em>From CCSID</em> values match, it is the same as if the object
would have been opened in binary.</p>
<p><strong>Length of status information.</strong>
The length in bytes allocated for the returned status information.</p>
<p><strong>Object modified since last scan.</strong>
Whether the exit program was called because the objects data or CCSID has been modified
since it was last scanned.
Examples of object data or CCSID modifications are: writing to the object,
directly or through memory mapping; truncating the object; clearing the object;
and changing the objects CCSID attribute, etc..
The possible values are:</p>
<table cellpadding="5">
<!-- cols="25 75" -->
<tr>
<td valign="top"><em>QP0L_SCAN_NO (x'00')</em></td>
<td valign="top">The object has not been modified since it was
last scanned.</td>
</tr>
<tr>
<td valign="top"><em>QP0L_SCAN_YES (x'01')</em></td>
<td valign="top">The object has been modified since it was
last scanned.</td>
</tr>
</table>
<p><strong>Object type.</strong>
The object type. See <a href=
"../rbam6/rbam6clmain.htm">Control Language (CL)</a> information in the iSeries
Information Center for descriptions of all object types.
</p>
<p><strong>Oflags.</strong>
The oflags that were specified on the open request associated with this close
request with the following exceptions. For a description of all possible
oflag values, see <a href="open.htm">open()--Open a File.</a></p>
<ul>
<li>If the oflags do not contain write access, the system will
attempt to upgrade the access intent to include write, unless the
Scan file systems control (QSCANFSCTL) system value has
*NOWRTUPG specified
or the object is not eligible for write access.
If the upgrade is not attempted or
is unsuccessful, the access intent matches the users invocation.
If it is successful, the write access intent is included in this oflag information.
This upgrade would be useful if the exit program wanted to modify the object
to correct any problems found while scanning.</li>
<li>The CCSID related flags will have been removed. This includes
O_TEXTDATA, O_CCSID, O_CODEPAGE, and O_TEXT_CREATE.</li>
<li>The synchronization flags will have been removed. This includes
O_SYNC, O_DSYNC, and O_RSYNC.
</ul>
<p><strong>Scan descriptor.</strong>
A descriptor representing the object that is being closed. This scan descriptor
has the following characteristics:</p>
<ul>
<li>It can be used to do any read processing on the object being processed.
Reads using this descriptor will not update the last access timestamp information
for the object.</li>
<li>It can be used to do any write processing on the object being processed.
If write processing is done by the exit program, the exit program should indicate
QP0L_SCAN_MODIFY in the <em>Scan status</em> field. If it does not, the
object's scan information will be cleared as if the objects data has been modified.</li>
<li>It cannot be used to memory map the object, see
<a href="mmap.htm">mmap()--Memory Map a File.</a></li>
<li>It cannot be used to close the object using
<a href="close.htm">close()--Close File or Socket Descriptor</a>.
When control returns from the exit program, the system code will do the close of this
<em>scan descriptor</em>. The system will wait on this close attempt until all
accesses to this object are closed. Therefore, if the exit program uses
<a href="gvsoc.htm">givedescriptor()--Pass Descriptor Access to Another
Job</a> and
<a href="tksoc.htm">takedescriptor()--Receive Socket Access from Another
Job</a> or
<a href="sendms.htm">sendmsg()--Send Data or Descriptors or Both</a> and
<a href="recvms.htm">recvmsg()--Receive Data or Descriptors or Both</a>
to pass the descriptor to another job, the job which used
takedescriptor() or recvmsg()
must close that descriptor when it is done processing,
else the system will be waiting for that close.</li>
<li>
<a href="dup.htm">dup()--Duplicate Open File Descriptor</a>
and <a href="fcntl.htm">fcntl()--Perform File Control
Command</a> with F_DUPFD
cannot be used to duplicate the <em>scan descriptor</em>.
This is so the system has tight control of the closing of
this scan descriptor.</li>
<li>Data read using this descriptor will be in the <em>From CCSID</em> format.
If any data is written using this descriptor, it must be in the
<em>From CCSID</em> format.
For more information on CCSIDs see
<a href="ifsopenexit.htm#HDRSCCSID">Coded Character Set Identifier (CCSID) Information</a>
in <a href="ifsopenexit.htm">Integrated File System Scan on Open Exit Program</a>. </li>
<li>It will be a different descriptor than was specified on the close request. </li>
<li>The oflags for this descriptor are what are passed on this interface.</li>
<li>It is scoped to the process. However, one can use
<a href="gvsoc.htm">givedescriptor()</a>
and <a href="tksoc.htm">takedescriptor()</a>
or <a href="sendms.htm">sendmsg()</a> and
<a href="recvms.htm">recvmsg()</a>
to pass this descriptor to
another job or process. Again, that process must complete its use of that
descriptor before control is returned to the system from the exit program
because the system will close the descriptor when exit program processing is complete.
The system will wait on this close attempt until all
accesses to this object are closed.</li>
<li>No other threads in the process, other than those created by the
exit program, will be able to access this descriptor.</li>
<li>It only lives for the life of the exit program invocation.
That is, once control is returned from the exit program, it will
be destroyed. Therefore, it cannot be stored for later use.</li>
</ul>
<p><strong>Scan key.</strong>
The scan key associated with this exit program.
The first character of this scan key can not be hex zeros or a blank.
For more information on the scan key,
see <A href="ifsopenexit.htm#HDRSCkey">Scan Key List and Scan Key Signatures</a> in
<a href="ifsopenexit.htm">Integrated File System Scan on Open Exit Program</a>.
</p>
<p><strong>Scan key signature.</strong>
The scan key signature associated with the specified <em>scan key</em>.
For more information on the scan key signature,
see <A href="ifsopenexit.htm#HDRSCkey">Scan Key List and Scan Key Signatures</a> in
<a href="ifsopenexit.htm">Integrated File System Scan on Open Exit Program</a>.
If the specified <em>scan key</em> already exists in the scan key list,
and the exit program is being added to replace an existing exit program
entry, then the specified <em>scan key signature</em> must match the
scan key signature associated with the scan key in the scan key list.
If the specified <em>scan key</em> already exists in the scan key list,
and the exit program is <strong>not</strong> being added to replace an
existing exit program
entry, then the specified <em>scan key signature</em> must match the
scan key signature associated with the scan key in the scan key list
unless the scan key signature associated with the scan key in the scan
key list is all hex zeros.
More than one exit program, including exit programs associated with the
<a href="ifsopenexit.htm">Integrated File System Scan on Open Exit Program</a>,
can have the same scan key signature.
</p>
<p><strong>Scan signatures different.</strong>
Whether the exit program was called because the object's current
scan key signature is different than the appropriate associated signature.
When an object is in an independent ASP group, the object scan signature is compared
to the associated independent ASP group scan signature.
When an object is <strong>not</strong> in an independent ASP group, the object
scan signature is compared to the global scan signature.
The possible values are:</p>
<table cellpadding="5">
<!-- cols="25 75" -->
<tr>
<td valign="top"><em>QP0L_SCAN_NO (x'00')</em></td>
<td valign="top">The compared signatures are not different.</td>
</tr>
<tr>
<td valign="top"><em>QP0L_SCAN_YES (x'01')</em></td>
<td valign="top">The compared signatures are different.</td>
</tr>
</table>
<p><strong>Scan status.</strong>
The status of the scan processing.
This field is only used if the <em>Update object scan information</em>
field value specifies a value of QP0L_SCAN_YES.
The possible values are:</p>
<table cellpadding="5">
<!-- cols="25 75" -->
<tr>
<td valign="top"><em>QP0L_SCAN_SUCCESS (x'01')</em></td>
<td valign="top">The object was scanned and has no failures.
If this indicator is returned by all exit programs that were called,
the object will be marked as scan successful, and
the close operation completes with no errors.</td>
</tr>
<tr>
<td valign="top"><em>QP0L_SCAN_FAILURE (x'02')</em></td>
<td valign="top">The object was scanned and has at least one failure.
If this indicator is returned by at least one of the exit programs that was called,
the object will be marked as scan failure, and
the close operation fails.
Additionally, only the CCSID or binary indication related to this failing request will
be kept in the object scan information, and the rest of the historical CCSID or binary
information will be cleared.
<p> Once an object has been marked as a failure under this condition,
it will not be scanned again
until the object's scan signature is different than the global scan key signature
or independent ASP group scan key signature as appropriate. Therefore, subsequent
requests to work with the object will fail with a scan failure indication.
Examples of requests which will fail are opening the object,
changing the CCSID of the object, copying the object etc..</p>
</td>
</tr>
<tr>
<td valign="top"><em>QP0L_SCAN_FAIL_WANT_ MODIFY (x'03')</em></td>
<td valign="top">The object was scanned and has at least one failure. However,
the exit program wanted to modify the file to correct the failure, but could not
because it did not have write access.
If this indicator is returned by at least one of the exit programs that was called,
the object will be marked as scan failure, and
the close operation fails.
Additionally, only the CCSID or binary indication related to this failing request will
be kept in the object scan information, and the rest of the historical CCSID or binary
information will be cleared.
<p> Once an object has been marked as a failure under this condition,
it will not be scanned again
until the object's scan signature is different than the global scan key signature
or independent ASP group scan key signature as appropriate, or if a subsequent access
would allow write access to be given to the exit program.
Therefore, subsequent
requests to work with the object will fail with a scan failure indication.
Examples of requests which will fail are opening the object,
changing the CCSID of the object, copying the object etc..</p>
</td>
</tr>
<tr>
<td valign="top"><em>QP0L_SCAN_MODIFY (x'04')</em></td>
<td valign="top">The object was scanned, one or more failures were found,
but the object was modified to remove the failures.
If this indicator is returned by at least one of the exit programs that was called,
then any exit programs which have previously been called will be
called one more time so that they can scan
the modified object information. This second call is indicated by an
<em>Additional call</em> field value. If after this additional call,
no failures are found, the object will be marked as scan successful, and
the close operation completes with no errors.
</td>
</tr>
</table>
If a value other than the possible values is
specified, the object will be treated as if the program was not called
and the object was not scanned. Therefore, the close operation will continue
unless the Scan file systems control (QSCANFSCTL) system value has
*ERRFAIL specified which will cause the operation to fail.
If the Scan file systems
control (QSCANFSCTL) system value has *NOFAILCLO specified, the close operation
will not return any failure indication. If *NOFAILCLO is not specified,
the close operation will fail with error code [ESCANFAILURE].
<p><strong>To CCSID.</strong>
The CCSID value that was specified on the open request
associated with this close request. Therefore, this
will be the CCSID in which data was returned (when the user
was reading from the object), or the CCSID in which data was
be supplied (when the user was writing to the object).
Therefore, the exit program should be converting the data to this CCSID since
this is how the data was presented to the user after their open
request completed.
For more information on CCSIDs and conversions,
see <a href="ifsopenexit.htm#HDRSCCSID">Coded Character Set Identifier (CCSID) Information</a> in
<a href="ifsopenexit.htm">Integrated File System Scan on Open Exit Program</a>.
</p>
<p><strong>Note:</strong> If the <em>To CCSID</em> and
<em>From CCSID</em> values match, it is the same as if the object
was opened in binary.</p>
<p><strong>Update object scan information.</strong>
Whether the scan information associated with the object should be updated or not.
The object scan information includes the following:</p>
<ul>
<li>Scan status for the object.</li>
<li>Scan signature associated with the object scan status.</li>
<li>The <em>To CCSID</em> value of the object which was scanned or if the object was scanned
in binary.
<p><strong>Note:</strong> Actually, the last two To CCSID values which have been scanned
will be maintained as well as a separate indication of binary scans.</p> </li>
</ul>
<p>The possible values are:</p>
<table cellpadding="5">
<!-- cols="25 75" -->
<tr>
<td valign="top"><em>QP0L_SCAN_NO (x'00')</em></td>
<td valign="top">The object scan information should not be updated. This might be
used when the object was not actually scanned by the exit program, perhaps because
it did not need to be, or perhaps because a deferred scan was initiated.
</td>
</tr>
<tr>
<td valign="top"><em>QP0L_SCAN_YES (x'01')</em></td>
<td valign="top">The object scan information should be updated. When this value
is set, then the values in the <em>Scan status</em> field
and <em>Failing CCSID</em> are used.
If at least one exit program specified
this value, then the object scan information will be updated.
</td>
</tr>
</table>
If a value other than the possible values is specified, a value of QP0L_SCAN_NO
is assumed.
<p><strong>User profile.</strong>
The exit program will be called under this user profile.
Therefore, this user profile should have *USE authority to
the exit program, and *EXECUTE authority to the exit program library.
If the user profile is not valid or accessible at the time the exit program
is called, the object will be treated as if the program was not called
and the object was not scanned. Therefore, the close operation will continue
unless the Scan file systems control (QSCANFSCTL) system value has
*ERRFAIL specified which will cause the operation to fail.
If the Scan file systems
control (QSCANFSCTL) system value has *NOFAILCLO specified, the close operation
will not return any failure indication. If *NOFAILCLO is not specified,
the close operation will fail with error code [ESCANFAILURE].
The first character of the user profile can not be hex zeros or a blank.
</p>
<p><strong>Note:</strong> The system will not do any additional verification
that this specified profile has authority to the object for which the exit
program is being called when that exit program is being called, even when
the access levels for the object are upgraded to include write.
By registering this exit program, you are indicating this is acceptable.
</p>
<br>
<h3><a name="HDRSCCLU">Usage Notes</a></h3>
<ol>
<li>When the exit program is executing (including any created threads),
if it does any operations on other objects which might normally trigger another
call to a scan-related exit program, the scan-related exit program will
<strong>not</strong> be called, and it
will be treated as if no scanning occurred for the object. For example,
if the exit program opens a separate object, that object will not be scanned
as part of that open request, even if an exit program is registered to the
QIBM_QP0L_SCAN_OPEN exit point.
If however, that object has previously
failed a scan, then the operation will fail with error code [ESCANFAILURE].
<br><br></li>
<li>When the exit program is executing (including any created threads),
if it does any opens of other objects, then the descriptors
which will be returned will come from the same table of descriptors
that the <em>Scan descriptor</em> is derived from. Therefore,
customer application code will not be impacted by 'regular'
descriptors being used and possibly reaching an application specified limit
on the number of descriptors which can be used.
Additionally, the exit program will not be able to use any of the
'regular' descriptors when it or any of its created threads are
executing. That is, it will not be able to access any objects
which have been opened outside the scope of the exit program
execution. Any attempts to do so will fail with error code [EBADF].
<br><br></li>
<li>When the following APIs are called from the thread executing the exit
program and any of its created threads, the table of
<em>Scan descriptors</em>,
will not be inherited by the spawned process.
<ul>
<li><a href="spawn.htm">spawn()</a>--Spawn Process</li>
<li><a href="spawnp.htm">spawnp()</a>--Spawn Process with Path</li>
</ul>
<p>Therefore, when the following APIs are called from the thread executing the exit
program and any of its created threads, the descriptors returned by these
APIs will only work within the same process.</p>
<ul>
<li><a href="pipe2.htm">pipe()</a>--Create Interprocess Channel</li>
<li><a href="pipe.htm">Qp0zPipe()</a>--Create Interprocess Channel with Sockets()</li>
</ul>
<br></li>
<li>When the exit programs are executing (including any created threads),
signals are blocked from being delivered to a thread.
When a signal is blocked, the signal-handling action associated
with the signal is not taken. The signal remains pending
until all exit programs have completed execution. For more information,
see <A href="unix5a2.htm#sigconcepts">Signal concepts</a>.
<br><br></li>
<li>When the following APIs are called from the thread executing the exit
program and any of its created threads,
they will fail with the listed error code.
<ul compact>
<li><a href="dossfllk.htm">DosSetFileLocks()--Lock and Unlock a Byte Range
of an Open File</a>-- [ENOTSUP]</li>
<li><a href="dossfl64.htm">DosSetFileLocks64()--Lock and Unlock a Byte Range
of an Open File (Large File Enabled)</a>-- [ENOTSUP]</li>
<li><a href="dossrmfh.htm">DosSetRelMaxFH()--Change maximum number of file
descriptors</a> -- [ERROR_GEN_FAILURE]</li>
<li><a href="dup2.htm">dup2()--Duplicate Open File Descriptor to Another
Descriptor</a> -- [ENOTSUP]</li>
<li><a href="fcntl.htm">fcntl()--Perform File Control
Command</a> with F_SETLK, F_SETLK64, F_SETLKW or F_SETLKW64 -- [ENOTSUP]
</li>
<li><img src="delta.gif" alt="Start of change">
<a href="recvms.htm">recvmsg()--Receive Data or Descriptors or Both</a>-- [ENOTSUP]
</li>
<li>
<a href="socketp.htm">socketpair()--Create a Pair of Sockets</a>-- [ENOTSUP]
<img src="deltaend.gif" alt="End of change">
</li>
<li><a href="tksoc.htm">takedescriptor()--Receive Socket Access from Another
Job</a> -- [ENOTSUP]<br><br></li>
</ul>
</li>
<li>
Unpredictable results will occur
if the <a href="sselect.htm">select()--Wait for events on multiple sockets</a>
<img src="delta.gif" alt="Start of change">
or <a href="poll.htm">poll()--Wait for events on multiple descriptors</a>
<img src="deltaend.gif" alt="End of change">
APIs and any of their associated type and macro definitions are used in
the thread executing the exit program and any of its created threads.
Therefore, these interfaces should not be used under these conditions.<br><br>
</li>
<li>
It is recommended that the exit program use the large-file enabled APIs
such as <a href="lseek64.htm">lseek64()--Set File Read/Write Offset (Large File
Enabled)</a> to work with the <em>scan descriptor</em>
as these APIs will work with any size object.<br><br></li>
<li>If Kerberos is configured on the system, then the thread executing the exit
program and any of its created threads will not be able to access objects in
any file systems which use Kerberos for authentication. If they do, the
operation will fail with error code [ENOTSUP]. E.g. the exit program
cannot access objects in the QFileSvr.400 file system when Kerberos is configured.<br><br></li>
<li>The exit program should not call the open or close API interfaces on the object
represented by the <em>scan descriptor</em>. If this is done from the thread executing the
exit program, then [EDEADLK] will be returned. If the
object is opened or closed from any other process or thread,
that process or thread will wait until this invocation's scan is completed.</li>
</ol>
<h3>Related Information</h3>
<ul>
<li>The &lt;<strong>qp0lscan.h</strong>&gt; file
(see <a href="unix13.htm">Header Files for UNIX-Type Functions</a>)</li>
<li>
<a href="chgscansgn.htm">Change Scan Signature (QP0LCHSG) API</a></li>
<li>
<a href="ifsopenexit.htm">Integrated File System Scan on Open Exit Program</a></li>
<li>
<A href="qgetattr.htm">Qp0lGetAttr()--Get Attributes</a></li>
<li>
<A href="qsetattr.htm">Qp0lSetAttr()--Set Attributes</a></li>
<li>
<a href="rtvscansgn.htm">Retrieve Scan Signature (QP0LRTSG) API</a></li>
<li>
<a href="qwcrsval.htm">Retrieve System Values (QWCRSVAL) API</a></li>
</ul>
<hr>
Exit program introduced: V5R3
<hr>
<center>
<table cellpadding="2" cellspacing="2" width="600">
<tr align="center">
<td valign="middle" align="center"><a href="#Top_Of_Page">Top</a>
| <a href="unix2.htm">Integrated File System APIs</a>
| <a href="aplist.htm">APIs by category</a> </td>
</tr>
</table>
</center>
</body>
</html>
Reference in New Issue Copy Permalink