#include <qp0lchsg.h>
void QP0LCHSG
(void *ScanKey_Ptr,
void *ScanSign_Ptr,
void *Error_Code_Ptr);
Default Public Authority: *USEThe Change Scan Signature (QP0LCHSG) API 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.
The integrated file system scan-related exit points are:
To retrieve the scan key signature currently associated with a specific scan key, see Retrieve Scan Signature(QP0LRTSG) API. For more information about the integrated file system scan processing, see the Integrated file system topic collection.
If the scan key has not yet been registered with any scan-related exit program, CPFA0EA is sent.
See Scan Key List and Scan Key Signatures in Integrated File System Scan on Open Exit Program for more information.
(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 scan key.
If a value of all hex zeroes is specified, CPFA0EB is sent.
If the specified scan key signature is a different value than the current scan key signature associated with the specified scan key, 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 scan key, will be updated.
Note: 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.
If the specified scan key signature matches the current scan key signature associated with the specified scan key, 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.
See Scan Key List and Scan Key Signatures in Integrated File System Scan on Open Exit Program for more information.
The following messages may be sent from this function:
| Message ID | Error Message Text |
|---|---|
| CPF3C36 E | Number of parameters, &1, entered for this API was not valid. |
| CPF3CD9 E | Requested function cannot be performed at this time. |
| CPF3CF1 E | Error code parameter not valid. |
| CPF3CF2 E | Error(s) occurred during running of &1 API. |
| CPF9872 E | Program or service program &1 in library &2 ended. Reason code &3. |
| CPFA0B1 E | Requested operation not allowed. Access problem. |
| CPFA0D4 E | File system error occurred. Error number &1. |
| CPFA0EA E | Scan key &1 does not exist. |
| CPFA0EB E | Invalid scan key signature &2 specified. |
The following is an example showing a call to the Change Scan Signature (QP0LCHSG) and the Retrieve Scan Signature (QP0LRTSG) APIs.
Note: By using the code examples, you agree to the terms of the Code license and disclaimer information.
#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);
}