QsyChangeValidationLstEntry()--Change Validation List Entry API

  #include <qsyvldl.h>

  int QsyChangeValidationLstEntry
         (Qsy_Qual_Name_T             *Validation_Lst,
          Qsy_Entry_ID_Info_T         *Entry_ID,
          Qsy_Entry_Encr_Data_Info_T  *Encrypt_Data,
          Qsy_Entry_Data_Info_T       *Entry_Data,
          void                        *Attribute_Info);

The QsyChangeValidationLstEntry() function changes an entry in a validation list object. The data to be encrypted, the entry data values, and some of the entry attributes may be changed.

To identify an entry to be changed, there must be an exact match in the entry for the value that is specified in the Entry_ID parameter and the length of the entry ID. For example, an entry ID value of "SMITH" with a length of 5 would not allow you to change an entry where the entry ID is "SMITH" and the length is 7.

Conversions are not done on any data when entries are changed. The CCSID values are stored as part of the record, to be available to the user of the API, but are not used when the entry is changed.

Authorities

Validation List Object

*USE and *UPD

Validation List Object Library

*EXECUTE

Parameters

Validation_Lst

(Input)

A pointer to the qualified object name of the validation list that contains the entry to change. The first 10 characters specify the validation list name, and the second 10 characters specify the library. You can use these special values for the library name:

*CURLIB	The current library is used to locate the validation list. If there is no current library, QGPL (general purpose library) is used.
*LIBL	The library list is used to locate the validation list.

Entry_ID

(Input)

A pointer to the entry ID information. The Qsy_Entry_ID_Info_T structure is as follows:

int	Entry_ID_Len	The number of bytes of data that is provided as the entry ID. Possible values are from 1 through 100.
unsigned int	Entry_ID_CCSID	An integer that represents the CCSID for the entry ID. Valid CCSID values are in the range 0 through 65535. This field is not used to change the entry.
unsigned char	Entry_ID[]	The data that is used to identify this entry in the validation list.

Encrypt_Data

(Input)

A pointer to the data that is associated with the entry ID. The data is encrypted by the system when it is stored. If the pointer is NULL, the encrypted data that is associated with the entry ID is not changed. The format of the Qsy_Entry_Encr_Data_Info_T structure is as follows:

int	Encr_Data_Len	The number of bytes of data to be encrypted and stored in this validation list entry. Possible values are from 0 through 600.
unsigned int	Encr_Data_CCSID	An integer that represents the CCSID for the data to encrypt. Valid CCSID values are in the range 1 through 65535. The special value follows: 0 The default CCSID for the current user is stored.
unsigned char	Encr_Data[]	The data to be encrypted before storing it in the validation list entry.

If Encr_Data_Len is 0, any encrypted data that is associated with the entry ID will be removed.

Entry_Data

(Input)

A pointer to the data information that is associated with the entry ID. If the pointer is NULL, the data that is associated with the entry ID is not changed. The format of the Qsy_Entry_Data_Info_T structure is as follows:

int	Entry_Data_Len	The number of bytes of data to be stored in this validation list entry. Possible values are from 0 through 1000.
unsigned int	Entry_Data_CCSID	An integer that represents the CCSID for the data. Valid CCSID values are in the range 1 through 65535. The special value follows: 0 The default CCSID for the current user is stored.
unsigned char	Entry_Data[]	The data to be stored in the validation list entry.

If the Entry_Data_Length is 0, any data that is associated with the entry ID will be removed.

Attribute_Info

(Input)

A pointer to a structure that contains attribute information that is associated with the entry ID. If the pointer is NULL, the attributes associated with the entry ID are not changed. The format of the Qsy_Attr_Info_T structure is as follows:

int	Number_Attrs	The number of attributes being changed. This value must be greater than 0.
char	Res_Align[12]	Reserved for boundary alignment.
Qsy_Attr_Descr_T	Attr_Descr[]	An array of attribute description structures.

The format of the Qsy_Attr_Descr_T structure is as follows:

int	Attr_Location	Where the attribute should be stored. The allowed value follows: 0 QSY_IN_VLDL The attribute is stored in the validation list object.
int	Attr_Type	The type of attribute. The allowed value follows: 0 QSY_SYSTEM_ATTR This is a system-defined attribute.
union	Attr_Res Res_1[8]	Reserved data. This value must be hexadecimal zero.
char *	Attr_ID	The ID of the attribute. For system-defined attributes, the allowed value is:
	String value	Description
	QsyEncryptData	This is the attribute that is associated with the data to encrypt. This attribute can only be changed if the Encrypt_Data parameter is not NULL.
union	Attr_Other_Descr Res_1[32]	Reserved data. This value must be hexadecimal zero.
union	Attr_Data_Info	The information that describes the attribute data.
union	Attr_Other_Data Res_1[32]	Reserved data. This value must be hexadecimal zero.

The format of the Attr_Data_Info_T union is as follows:

Qsy_In_VLDL_T	Attr_VLDL	The attribute data information for an attribute that is stored in the validation list object.
union	Attr_In_Other Res_1[96]	Reserved data. The last 64 bytes must be zero.

The format of the Qsy_In_VLDL_T structure is as follows:

int	Attr_CCSID	An integer that represents the CCSID for the attribute. Valid CCSID values are in the range -1 through 65535. The special values follow: -1 No CCSID value is stored with the attribute. If the attribute is QsyEncryptData, this value is assumed. 0 The default CCSID for the current user is stored.
int	Attr_Len	The number of bytes of data in the attribute value. The length must be greater than or equal to 0. If a length of 0 is specified, the attribute is removed from the entry. For the QsyEncryptData attribute, the maximum length is 1.
union	Attr_Res Res_1[8]	Reserved data. This value must be hexadecimal zero.
void *	Attr_Value	Pointer to the value of the attribute associated with the entry. For the QsyEncryptData attribute, the allowed values follow: 0 QSY_VFY_ONLY The data to be encrypted can only be used to verify an entry. This is the default. 1 QSY_VFY_FIND The data to be encrypted can be used to verify an entry and can be returned on a find operation.

If the QSY_VFY_FIND value is specified for the QsyEncryptData attribute, the system value QRETSVRSEC (Retain server security data) is used to determine if the data to be encrypted is stored in the entry or not. If the system value is set to 0 (Do not retain data), the entry will be changed, but the data to be encrypted will not be stored with the entry. The return value from this function will be -2, to indicate that the entry was changed, but the data to be encrypted was not stored. If the system value is set to 1 (Retain data), then the data to be encrypted will be stored when the entry is changed.

Return Value

Error Conditions

If QsyChangeValidationLstEntry() is not successful, errno indicates one of the following errors.

Example

See Code disclaimer information for information pertaining to code examples.

The following example changes an entry for a user named FRED in the validation list object WEBUSRS. FRED's encrypted data (password) and the CCSID for the encrypted data are being changed, but not any other data.

#include <qsyvldl.h>

main()
{
  #define VLD_LST  "WEBUSRS   WEBLIB    "
  Qsy_Entry_ID_Info_T    entry_info;
  Qsy_Entry_Encr_Data_Info_T  encrypt_data;

  entry_info.Entry_ID_Len = 4;
  strncpy(entry_info.Entry_ID,"FRED",entry_info.Entry_ID_Len);
  encrypt_data.Encr_Data_Len = 7;
  encrypt_data.Encr_Data_CCSID = 37;
  strncpy(encrypt_data.Encr_Data,"MSN1TJG",
          encrypt_data.Encr_Data_Len);

  if (0 != QsyChangeValidationLstEntry(
                       (Qsy_Qual_Name_T *)&VLD_LST,
                       &entry_info,
                       &encrypt_data,
                       NULL,
                       NULL))
     perror("QsyChangeValidationLstEntry()");

}