Change Scan Signature (QP0LCHSG) API

 #include <qp0lchsg.h>
 void QP0LCHSG
              (void      *ScanKey_Ptr,
               void      *ScanSign_Ptr,
               void      *Error_Code_Ptr);

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 on the integrated file system scan processing, see the Integrated file system information in the Files and file systems topic.

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:

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

See Code disclaimer information for information pertaining to code examples.

The following is an example showing a call to the Change Scan Signature (QP0LCHSG) and the Retrieve Scan Signature (QP0LRTSG) APIs.

#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);
}