333 lines
11 KiB
HTML
333 lines
11 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>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>
|
||
|
|
Syntax<br>
|
||
|
|
|
||
|
|
<pre>
|
||
|
|
#include <qp0lchsg.h>
|
||
|
|
void QP0LCHSG
|
||
|
|
(void *<em>ScanKey_Ptr</em>,
|
||
|
|
void *<em>ScanSign_Ptr</em>,
|
||
|
|
void *<em>Error_Code_Ptr</em>);
|
||
|
|
|
||
|
|
</pre>
|
||
|
|
|
||
|
|
Default Public Authority: *USE<br>
|
||
|
|
<!-- iddvc RMBR -->
|
||
|
|
<br>
|
||
|
|
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, &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 &1 API.</td>
|
||
|
|
</tr>
|
||
|
|
|
||
|
|
<tr>
|
||
|
|
<td valign="top">CPF9872 E</td>
|
||
|
|
<td valign="top">Program or service program &1 in library &2 ended.
|
||
|
|
Reason code &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 &1.</td>
|
||
|
|
</tr>
|
||
|
|
|
||
|
|
<tr>
|
||
|
|
<td valign="top">CPFA0EA E</td>
|
||
|
|
<td valign="top">Scan key &1 does not exist.</td>
|
||
|
|
</tr>
|
||
|
|
|
||
|
|
<tr>
|
||
|
|
<td valign="top">CPFA0EB E</td>
|
||
|
|
<td valign="top">Invalid scan key signature &2 specified.</td>
|
||
|
|
</tr>
|
||
|
|
</table>
|
||
|
|
|
||
|
|
<br>
|
||
|
|
<br>
|
||
|
|
|
||
|
|
<h3>Related Information</h3>
|
||
|
|
|
||
|
|
<ul>
|
||
|
|
<li>The <<strong>qp0lchsg.h</strong>> 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 <qp0lchsg.h>
|
||
|
|
#include <qp0lrtsg.h>
|
||
|
|
#include <qusec.h>
|
||
|
|
#include <stdio.h>
|
||
|
|
#include <string.h>
|
||
|
|
#include <stdlib.h>
|
||
|
|
|
||
|
|
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(&scankey, "KEY1 ",sizeof(scankey));
|
||
|
|
/* Determine if scan key exists and what it's signature is */
|
||
|
|
QP0LRTSG(&scankey,
|
||
|
|
&scankeysign,
|
||
|
|
&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,
|
||
|
|
&scankeysign,
|
||
|
|
sizeof(scankeysign)))
|
||
|
|
{
|
||
|
|
printf("Current signature = %.12s", scankeysign);
|
||
|
|
return(0);
|
||
|
|
}
|
||
|
|
else
|
||
|
|
{
|
||
|
|
memcpy(&scankeysign, "NEWSIGN ",sizeof(scankeysign));
|
||
|
|
/* Update signature information */
|
||
|
|
QP0LCHSG(&scankey,
|
||
|
|
&scankeysign,
|
||
|
|
&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>
|
||
|
|
|