Change Scan Signature (QP0LCHSG) API
Syntax
#include <qp0lchsg.h> void QP0LCHSG (void *ScanKey_Ptr, void *ScanSign_Ptr, void *Error_Code_Ptr);Default Public Authority: *USE
Threadsafe: Yes
The 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:
- Integrated File System Scan on Close Exit Programs
- Integrated File System Scan on Open Exit Programs.
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.
Parameters
- ScanKey_Ptr
- (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.
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.
- ScanSign_Ptr
-
(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.
- Error_Code_Ptr
- (Input/Output) Pointer to an error code structure to receive error
information. See Error code parameter for
more information.
Authorities
- User Profile Authority
- *ALLOBJ (all object) and *SECADM (security administrator) special authorities to use this API
Error Messages
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. |
Related Information
- The <qp0lchsg.h> file (see Header Files for UNIX®-Type Functions)
- Integrated File System Scan on Close Exit Program
- Integrated File System Scan on Open Exit Programs
- Retrieve Scan Signature (QP0LRTSG) API
- Qp0lGetAttr()--Get Attributes
- Qp0lSetAttr()--Set Attributes
Example
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); }
API introduced: V5R3