1203 lines
50 KiB
HTML
1203 lines
50 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>Integrated File System Scan on Open 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 -->
|
|
<!-- 010301 JTROUS Crt Date, based on XDLTRCV.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 -->
|
|
<!-- 040325 TIMCLARK Document restriction on virtual volumes, v5r4 -->
|
|
<!-- 040614 TIMCLARK Add poll() restriction, v5r4 -->
|
|
<!-- 040721 JTROUS Fix iSeries mentions, no change flag, V5r4 -->
|
|
<!-- 040806 JTROUS Fix up USAGE notes lists someone messed up, no chg flag -->
|
|
<!-- 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 Open Exit Program</h2>
|
|
|
|
<div class="box" style="width: 80%;">
|
|
<br>
|
|
|
|
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 open 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>
|
|
QSYSINC Member Name: QP0LSCAN<br>
|
|
<!-- iddvc RMBR -->
|
|
<br>
|
|
Exit Point Name: QIBM_QP0L_SCAN_OPEN<br>
|
|
<!-- iddvc RMBR -->
|
|
<br>
|
|
Exit Point Format Name: SCOP0100<br>
|
|
<!-- iddvc RMBR -->
|
|
<br>
|
|
</div>
|
|
|
|
<p>The integrated file system scan on open exit program is called to do scan
|
|
processing when an integrated file system object
|
|
is opened 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 is being opened for write access only.</li>
|
|
<li>-or- the object is being truncated as part of the open request.</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 is different than the
|
|
last two To CCSIDs that were specified and previously scanned for this object.</li>
|
|
<li>-or- the object is being opened in binary, 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>For more information on open processing, as well as CCSID values, see
|
|
<a href="open.htm">open()--Open File</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 open operation will continue
|
|
unless the QSCANFSCTL system value has
|
|
*ERRFAIL specified which will cause the operation to fail.</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 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:</li>
|
|
<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 opened that has a scan attribute of *YES,
|
|
and the open request is not through the file servers when
|
|
*FSVRONLY is specified. If O_FORCE_SCAN is specified on that open
|
|
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 opened with 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>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 open operation will continue
|
|
unless the Scan file systems control (QSCANFSCTL) system value has
|
|
*ERRFAIL specified which will cause the operation to fail.
|
|
</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="#HDRSCOPFD">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 open 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="#HDRSCOPFMT1">Format of
|
|
Integrated File System Open 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="#HDRSCOPFMT2">Format of
|
|
Status Information</a>.</p>
|
|
</dd>
|
|
</dl>
|
|
|
|
<br>
|
|
<h3><a name="HDRSCOPFMT1">Format of Integrated File System Open Exit
|
|
Information (Input)</a></h3>
|
|
|
|
<p>The following table shows the structure of the integrated file system open exit
|
|
information for exit point format SCOP0100. For a description of the fields in
|
|
this format, see <a href="#HDRSCOPFD">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 open 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">36</td>
|
|
<td align="center" valign="top">24</td>
|
|
<td align="left" valign="top">BINARY(4)</td>
|
|
<td align="left" valign="top">Scan descriptor</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">From 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">To 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), UNSIGNED</td>
|
|
<td align="left" valign="top">Last failure CCSID</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td align="center" valign="top">52</td>
|
|
<td align="center" valign="top">34</td>
|
|
<td align="left" valign="top">BINARY(4)</td>
|
|
<td align="left" valign="top">Oflags</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td align="center" valign="top">56</td>
|
|
<td align="center" valign="top">38</td>
|
|
<td align="left" valign="top">CHAR(16)</td>
|
|
<td align="left" valign="top">File ID</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td align="center" valign="top">72</td>
|
|
<td align="center" valign="top">48</td>
|
|
<td align="left" valign="top">CHAR(10)</td>
|
|
<td align="left" valign="top">Object type</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">File system</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td align="center" valign="top">83</td>
|
|
<td align="center" valign="top">53</td>
|
|
<td align="left" valign="top">CHAR(1)</td>
|
|
<td align="left" valign="top">Additional call</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td align="center" valign="top">84</td>
|
|
<td align="center" valign="top">54</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">85</td>
|
|
<td align="center" valign="top">55</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">86</td>
|
|
<td align="center" valign="top">56</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="HDRSCOPFMT2">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="#HDRSCOPFD">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">Open 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="HDRSCOPFD">Field Descriptions</a></h3>
|
|
|
|
<p><strong>Additional call.</strong>
|
|
Whether the exit program was called an additional time because another
|
|
<a href="ifsopenexit.htm">Integrated File System Scan on Open 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 60" -->
|
|
<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>Exit point format name.</strong>
|
|
The format name for the integrated
|
|
file system scan on open exit program. The possible format name follows:</p>
|
|
|
|
<table cellpadding="5">
|
|
<!-- cols="15 85" -->
|
|
<tr>
|
|
<td valign="top"><em>SCOP0100</em></td>
|
|
<td valign="top">The format name that is used while an object is being opened.</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="#HDRSCCSID">Coded Character Set Identifier (CCSID) Information</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 opened.
|
|
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</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.
|
|
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="#HDRSCCSID">Coded Character Set Identifier (CCSID) Information</a>.</p>
|
|
|
|
<p><strong>Integrated file system open exit information length.</strong>
|
|
The length in bytes of all data passed to the integrated file system open
|
|
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="#HDRSCCSID">Coded Character Set Identifier (CCSID) Information</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
|
|
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. </li>
|
|
</ul>
|
|
|
|
<p><strong>Open scan status information length.</strong>
|
|
The length in bytes of all data returned from the integrated file system open
|
|
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 open operation will continue
|
|
unless the Scan file systems control (QSCANFSCTL) system value has
|
|
*ERRFAIL specified which will cause the operation to fail.
|
|
</p>
|
|
|
|
<p><strong>Scan descriptor.</strong>
|
|
A descriptor representing the object that is being opened. 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="#HDRSCCSID">Coded Character Set Identifier (CCSID) Information</a>.</li>
|
|
<li>It will be a different descriptor than will actually be
|
|
returned to the user, if the open is ultimately successful. </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="#HDRSCkey">Scan Key List and Scan Key Signatures</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="#HDRSCkey">Scan Key List and Scan Key Signatures</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="ifscloseexit.htm">Integrated File System Scan on Close 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="30 70" -->
|
|
<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 open 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 open 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 open 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 open 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 open operation will continue
|
|
unless the Scan file systems control (QSCANFSCTL) system value has
|
|
*ERRFAIL specified which will cause the operation to fail.
|
|
|
|
<p><strong>To CCSID.</strong>
|
|
The CCSID value that was specified on the open request. Therefore, this
|
|
will be the CCSID in which data will be returned (when the user
|
|
will be reading from the object), or the CCSID in which data will
|
|
be supplied (when the user will be writing to the object).
|
|
Therefore, the exit program should be converting the data to this CCSID since
|
|
this is how the data will be presented to the user if the open
|
|
request completes successfully.
|
|
For more information on CCSIDs and conversions,
|
|
see <a href="#HDRSCCSID">Coded Character Set Identifier (CCSID) Information</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
|
|
will be 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 open operation will continue
|
|
unless the Scan file systems control (QSCANFSCTL) system value has
|
|
*ERRFAIL specified which will cause the operation to fail.
|
|
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="HDRSCkey">Scan Key List and Scan Key Signatures</a></h3>
|
|
<p>A list of <em>scan keys</em> and associated <em>scan key signatures</em>
|
|
will be used to help minimize unnecessary scan calls, while allowing users
|
|
to ensure scans occur when needed. The <em>scan key</em> list and <em>scan key signature</em>
|
|
will allow an association of scanning software level with the various scan-related exit programs
|
|
(<a href="ifscloseexit.htm">Integrated File System Scan on Close Exit Program</a> and
|
|
<a href="ifsopenexit.htm">Integrated File System Scan on Open Exit Program</a>).
|
|
Updates to this information will allow the system to increment its global
|
|
scan signature field to reflect the software updates.</p>
|
|
|
|
<p>The system will maintain a
|
|
global scan signature field and independent ASP group scan signature fields.
|
|
Each integrated file system object which supports scanning
|
|
will have an object scan signature field.</p>
|
|
|
|
<p>The global scan signature indicates the state or level of the scanning software.
|
|
It will or will not be modified under the following rules:</p>
|
|
<ul>
|
|
<li>When the scan-related exit programs are added or registered, the user specifies a scan key
|
|
and a scan key signature. These values are added to the scan key list.
|
|
If the scan key has previously been specified, e.g. for a different exit program registration,
|
|
then the global scan signature will only be incremented if the specified scan key signature
|
|
is not hex zero. If the scan key has not previously been specified, and
|
|
the scan key signature is not a hex zero value,
|
|
the global scan signature will be incremented.</li>
|
|
<li>By calling the
|
|
<a href="chgscansgn.htm">Change Scan Signature (QP0LCHSG) API</a>
|
|
to specify that a new scan key signature be associated with a specific scan key.
|
|
This will cause the system to update the scan key list and
|
|
increment the current global scan signature value.</li>
|
|
<li>When the scan-related exit programs are removed, the user specifies a scan key
|
|
and a scan key signature. These values are removed from the scan key list if no other
|
|
scan-related exit programs are registered that have that scan key. Removing entries from
|
|
the scan key list does <strong>not</strong> update the global scan signature.
|
|
</ul>
|
|
<p>The independent ASP group scan signature indicates the state of the scanning
|
|
software as well. Since it moves with the independent ASP group,
|
|
it represents the state of the scanning code software in relationship to when
|
|
and where that independent ASP group was varied on.
|
|
The independent ASP group scan key list and independent ASP group
|
|
scan signature will or will not be modified under the following rules:</p>
|
|
<ul>
|
|
<li>If the independent ASP group is available and online,
|
|
the independent ASP group scan key list
|
|
will be updated whenever the system scan key list is updated.
|
|
Any changes to the independent ASP group scan key list will cause the independent
|
|
ASP group scan signature to be incremented under the same rules as to when the
|
|
global scan signature is updated.</li>
|
|
<li>If the independent ASP group is varied on after any global scan key list
|
|
changes, then when the
|
|
first scannable integrated file system object
|
|
on the independent ASP group is opened or its scan information is retrieved,
|
|
the independent
|
|
ASP group scan key list will be compared to the global scan key list.
|
|
<ul>
|
|
<li>If the global
|
|
scan key list has more scan keys or different scan key signatures
|
|
than the independent ASP group scan
|
|
key list has, then the independent ASP group scan list will be updated
|
|
to match. Additionally, the independent ASP group scan signature will be incremented.</li>
|
|
<li>If the global
|
|
scan key list is a proper subset of the scan keys and scan key signatures
|
|
in the independent ASP group scan
|
|
key list, then the independent ASP group scan list will be updated
|
|
to match. However, the independent ASP group scan signature will
|
|
not be incremented.
|
|
If the global
|
|
scan key list exactly matchs the scan keys and scan key signatures
|
|
in the independent ASP group scan key list, then no changes are made.</li>
|
|
</ul>
|
|
</ul>
|
|
<p>It is highly recommended that the scanning software level of
|
|
support which is indicated by scan keys and scan key signatures be
|
|
maintained the same across all systems in the independent ASP
|
|
Cluster group. See <a href="clust1.htm">Cluster</a> for more information. </p>
|
|
|
|
<p>When an object in an independent ASP group is about to be scanned
|
|
or its scan information is retrieved, the
|
|
object scan signature will be 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 will be compared
|
|
to the global scan signature value.</p>
|
|
|
|
<p>When an object is successfully scanned, the object scan signature will be
|
|
updated to match the global scan signature or independent ASP group scan signature
|
|
when scanning was begun as appropriate. Other associated fields will be updated as
|
|
well as described in <em>Update object scan information.</em></P>
|
|
<br>
|
|
<h3><a name="HDRSCCSID">Coded Character Set Identifier (CCSID) Information</a></h3>
|
|
<p>The CCSID values presented on this interface have the following meanings
|
|
and inter-relationships. The <em>From CCSID</em> represents the value for the data
|
|
that is stored in the object. Therefore, when discussing reading and writing
|
|
in the <em>From CCSID</em> format, it means the data is read or written as is,
|
|
no conversion occurs between what is given to or returned by the system,
|
|
and the data in the object itself.
|
|
The <em>scan descriptor</em> that is passed to the
|
|
exit program is not an open instance which provides CCSID conversion. But,
|
|
when the object is ultimately opened, the file descriptor that is returned
|
|
will include conversion using the value in <em>To CCSID</em>.
|
|
If the <em>To CCSID</em> and
|
|
<em>From CCSID</em> values match, it is the same as if the object would have been
|
|
opened in binary. If the object is not being opened in binary, the scan
|
|
exit program should do its scanning using the <em>To CCSID</em> value, and can use
|
|
the appropriate APIs to do the conversion. If the scan succeeds or fails,
|
|
then the CCSID which is preserved with the scan status information is the
|
|
To CCSID, except for the following case. If the <em>Call after previous
|
|
failure</em> field has a value of QP0L_SCAN_YES, and the value in the <em>Last
|
|
Failure CCSID</em> is different than <em>To CCSID</em>, then the scan exit program should
|
|
also scan the object data using the <em>Last Failure CCSID</em>. In this case, if
|
|
the scan succeeds, then the CCSID which is preserved with the scan status
|
|
information is the <em>To CCSID</em>. If the scan fails, then the CCSID which is
|
|
preserved with the scan status information is the <em>Failing CCSID</em>.</p>
|
|
<p>For more information on CCSIDs and conversions,
|
|
see <a href="open.htm">open()--Open a File</a>
|
|
and <A href= "../nls/rbagsglobalmain.htm">Globalization</A> topic.
|
|
</p>
|
|
|
|
|
|
<br>
|
|
<h3><a name="HDRSCOPU">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.
|
|
<p>
|
|
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].
|
|
</p></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]
|
|
</ul>
|
|
<br><br></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 <<strong>qp0lscan.h</strong>> 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="ifscloseexit.htm">Integrated File System Scan on Close 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>
|
|
|