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

333 lines
11 KiB
HTML
Raw Blame History

<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8">
<meta name="Copyright" content="Copyright (c) 2006 by IBM Corporation">
<title>Change Scan Signature (QP0LCHSG) API</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 -->
<!-- 020110 JTROUS Crt date, based on qsetattr.htm, V5R3, DCR 98680 -->
<!-- 020417 JTROUS Major changes from I0 rework -->
<!-- 0206?? JET This file has undergone html cleanup June 2002 by JET -->
<!-- 020917 JTROUS Updates due to coding work -->
<!-- End Header Records -->
<link rel="stylesheet" type="text/css" href="../rzahg/ic.css">
</head>
<body><!-- Java sync-link -->
<script type="text/javascript" language="Javascript" src="../rzahg/synch.js">
</script>
<a name="Top_Of_Page"></a>
<h2>Change Scan Signature (QP0LCHSG) API</h2>
<div class="box" style="width: 70%;">
<br>
&nbsp;&nbsp;Syntax<br>
<pre>
#include &lt;qp0lchsg.h&gt;
void QP0LCHSG
(void *<em>ScanKey_Ptr</em>,
void *<em>ScanSign_Ptr</em>,
void *<em>Error_Code_Ptr</em>);
</pre>
&nbsp;&nbsp;Default Public Authority: *USE<br>
<!-- iddvc RMBR -->
<br>
&nbsp;&nbsp;Threadsafe: Yes<br>
<!-- iddvc RMBR -->
<br>
</div>
<p>The <strong>Change Scan Signature (QP0LCHSG) API</strong> changes the scan
key signature associated with a specific scan key. The scan key and scan key
signature are used with the integrated file system scan-related exit points to
indicate a software level which is to be associated with the exit points' exit
program registrations.</p>
<p>The integrated file system scan-related exit points are:</p>
<ul>
<li><a href="ifscloseexit.htm">Integrated File System Scan on Close Exit
Programs</a></li>
<li><a href="ifsopenexit.htm">Integrated File System Scan on Open Exit
Programs</a>.</li>
</ul>
<p>To retrieve the scan key signature currently associated with a specific scan
key, see <a href="rtvscansgn.htm">Retrieve Scan Signature(QP0LRTSG) API</a>.
For more information on the integrated file system scan processing, see the
<a href="../ifs/rzaaxkickoff.htm">Integrated file system</a> information
in the Files and file systems topic.</p>
<br>
<h3>Parameters</h3>
<dl>
<dt><strong><em>ScanKey_Ptr</em></strong></dt>
<dd>(Input) A pointer to a 20-byte character string that identifies the scan
key whose scan key signature is being changed. The scan key is one that was
specified when an exit program was registered or added to any of the integrated
file system scan-related exit points.<br>
<br>
<p>If the scan key has not yet been registered with any scan-related exit
program, CPFA0EA is sent.</p>
<p>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> for more information.</p>
</dd>
<dt><strong><em>ScanSign_Ptr</em></strong></dt>
<dd>
<p>(Input) A pointer to a 12-byte character string that identifies what the
scan key signature is to be changed to. A scan key signature value is
associated with a specific <em>scan key</em>.</p>
<p>If a value of all hex zeroes is specified, CPFA0EB is sent.</p>
<p>If the specified <em>scan key signature</em> is a different value than the
current scan key signature associated with the specified <em>scan key</em>,
then the global scan signature value
and any available independent ASPs scan signature values
will be incremented. Additionally, the exit
program registration information for any exit programs that are associated with
the integrated file system scan-related exit points whose scan key matches the
specified <em>scan key</em>, will be updated.</p>
<p><strong>Note:</strong> Because the exit program registration information is
part of the QUSRSYS library, then whenever the QUSEXRGOBJ object of type
*EXITRG is restored this information will be preserved.</p>
<p>If the specified <em>scan key signature</em> matches the current scan key
signature associated with the specified <em>scan key</em>, then the global scan
signature value
and any available independent ASPs scan signature values
will not be incremented, the associated exit program
registration information will not be updated, and no error message is
sent.</p>
<p>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> for more information.</p>
</dd>
<dt><strong><em>Error_Code_Ptr</em></strong></dt>
<dd>(Input/Output) Pointer to an error code structure to receive error
information. See <a href="../apiref/error.htm#hdrerrcod">Error code parameter</a> for
more information.<br>
<br>
</dd>
</dl>
<br>
<h3>Authorities</h3>
<dl>
<dt>User Profile Authority</dt>
<dd>*ALLOBJ (all object) and *SECADM (security administrator)
special authorities to use this API</dd>
</dl>
<br>
<h3>Error Messages</h3>
<p>The following messages may be sent from this function:</p>
<table width="100%" cellpadding="5">
<tr>
<th align="left" valign="top">Message ID</th>
<th align="left" valign="top">Error Message Text</th>
</tr>
<tr>
<td width="15%" valign="top">CPF3C36 E</td>
<td width="85%" valign="top">
Number of parameters, &amp;1, entered for this API was not valid.</td>
</tr>
<tr>
<td width="15%" valign="top">CPF3CD9 E</td>
<td width="85%" valign="top">
Requested function cannot be performed at this time.</td>
</tr>
<tr>
<td width="15%" valign="top">CPF3CF1 E</td>
<td width="85%" valign="top">Error code parameter not valid.</td>
</tr>
<tr>
<td valign="top">CPF3CF2 E</td>
<td valign="top">Error(s) occurred during running of &amp;1 API.</td>
</tr>
<tr>
<td valign="top">CPF9872 E</td>
<td valign="top">Program or service program &amp;1 in library &amp;2 ended.
Reason code &amp;3.</td>
</tr>
<tr>
<td valign="top">CPFA0B1 E</td>
<td valign="top">Requested operation not allowed. Access problem.</td>
</tr>
<tr>
<td valign="top">CPFA0D4 E</td>
<td valign="top">File system error occurred. Error number &amp;1.</td>
</tr>
<tr>
<td valign="top">CPFA0EA E</td>
<td valign="top">Scan key &amp;1 does not exist.</td>
</tr>
<tr>
<td valign="top">CPFA0EB E</td>
<td valign="top">Invalid scan key signature &amp;2 specified.</td>
</tr>
</table>
<br>
<br>
<h3>Related Information</h3>
<ul>
<li>The &lt;<strong>qp0lchsg.h</strong>&gt; file (see <a href="unix13.htm">
Header Files for UNIX-Type Functions</a>)</li>
<li><a href="ifscloseexit.htm">Integrated File System Scan on Close Exit
Program</a></li>
<li><a href="ifsopenexit.htm">Integrated File System Scan on Open Exit
Programs</a></li>
<li><a href="rtvscansgn.htm">Retrieve Scan Signature (QP0LRTSG) API</a></li>
<li><a href="qgetattr.htm">Qp0lGetAttr()</a>--Get Attributes.</li>
<li><a href="qsetattr.htm">Qp0lSetAttr()</a>--Set Attributes.</li>
</ul>
<br>
<h3>Example</h3>
<p>See <a href="../apiref/aboutapis.htm#codedisclaimer">Code disclaimer information</a>
for information pertaining to code examples.</p>
<p>The following is an example showing a call to the <strong>Change Scan
Signature (QP0LCHSG)</strong> and the <strong>Retrieve Scan Signature
(QP0LRTSG)</strong> APIs.</p>
<pre>
#include &lt;qp0lchsg.h&gt;
#include &lt;qp0lrtsg.h&gt;
#include &lt;qusec.h&gt;
#include &lt;stdio.h&gt;
#include &lt;string.h&gt;
#include &lt;stdlib.h&gt;
int main(int argc, char *argv[])
{
/*********************************************************************/
/* Variables used in this program. */
/*********************************************************************/
Qp0l_Scan_Key_t scankey;
Qp0l_Scan_KeySign_t scankeysign;
Qus_EC_t errorCode;
const char ZERO_SCAN_KEY_SIGNATURE[] = { 0x00, 0x00, 0x00,
0x00, 0x00, 0x00,
0x00, 0x00, 0x00,
0x00, 0x00, 0x00 };
/*********************************************************************/
/* */
/* $$$ Start of the executable code $$$ */
/* ---------------------------- */
/* */
/*********************************************************************/
/* Setup the error code structure to cause the error to be
returned within the error structure. */
errorCode.Bytes_Provided = sizeof(errorCode);
errorCode.Bytes_Available = 0;
memcpy(&amp;scankey, &quot;KEY1 &quot;,sizeof(scankey));
/* Determine if scan key exists and what it's signature is */
QP0LRTSG(&amp;scankey,
&amp;scankeysign,
&amp;errorCode);
/* Check if an error occurred. */
if (errorCode.Bytes_Available != 0)
{
printf("Error occurred for call to retrieve signature, QP0LRTSG.\n");
printf("Error message ID = %.7s", errorCode.Exception_Id);
return(0);
}
/* Is the current signature all zeros? if so we will update */
if (0!=memcmp(ZERO_SCAN_KEY_SIGNATURE,
&amp;scankeysign,
sizeof(scankeysign)))
{
printf("Current signature = %.12s", scankeysign);
return(0);
}
else
{
memcpy(&amp;scankeysign, "NEWSIGN ",sizeof(scankeysign));
/* Update signature information */
QP0LCHSG(&amp;scankey,
&amp;scankeysign,
&amp;errorCode);
/* Check if an error occurred. */
if (errorCode.Bytes_Available != 0)
{
printf("Error occurred for call to update signature, QP0LCHSG.\n");
printf("Error message ID = %.7s", errorCode.Exception_Id);
return(0);
}
else
{
printf("Signature updated by call to QP0LCHSG.\n");
printf("New signature = %.12s", scankeysign);
}
}
return(0);
}
</pre>
<p></p>
<hr>
API introduced: V5R3
<hr>
<center>
<table cellpadding="2" cellspacing="2">
<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 View Git Blame Copy Permalink