QsyAddValidationLstEntry()--Add Validation List Entry API

 #include <qsyvldl.h>

 int QsyAddValidationLstEntry
        (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 QsyAddValidationLstEntry() function adds an entry to a validation list object. Entries are stored in hexadecimal sort sequence. The first entry will always be the one in which the entry ID has the smallest hexadecimal value.

Conversions are not done on any data when entries are added. The CCSID value for each field is stored as part of the record but is not used when the entry is added to the validation list.

Authorities

Validation List Object

*USE and *ADD

Validation List Object Library

*EXECUTE

Parameters

Validation_Lst

(Input) A pointer to the qualified object name of the validation list to add the entry to. 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 format of 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 1 through 65535. The special value follows: 0 The default CCSID for the current user is stored.
unsigned char	Entry_ID[]	The data that is used to identify this entry in the validation list.

Encrypt_Data

(Input) A pointer to data that is associated with the entry ID and is encrypted by the system when it is stored. If the pointer is NULL, there is no encrypted data associated with the entry ID. 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 1 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.

Entry_Data

(Input) A pointer to the data information that is associated with the entry ID. If the pointer is NULL, there is no data associated with the entry ID. 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 1 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.

Attribute_Info

(Input) A pointer to a structure that contains attribute information that is associated with the entry ID. If the pointer is NULL, there is no attribute information associated with the entry ID. The format of the Qsy_Attr_Info_T structure is as follows:

int	Number_Attrs	The number of attributes being added. 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.
union	Attr_Other_Descr Res_1[32]	Reserved data. This value must be hexadecimal zero.
union	Attr_Data_Info	The information describing 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 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 must be specified. 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 0. For the QsyEncryptData attribute, the length must be 1.
union	Attr_Res Res_1[8]	Reserved data. This value must be hexadecimal zero.
void *	Attr_Value	A 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 added, 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 added, 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 added.

Return Value

Error Conditions

If QsyAddValidationLstEntry() is not successful, errno indicates one of the following errors:

Example

See Code disclaimer information for information pertaining to code examples.

The following example adds an entry for a user named FRED to the validation list object WEBUSRS. FRED has encrypted data (password), but no other data. The CCSID for the entry ID is set to the current user's default CCSID. The CCSID for the encryption data is set to 65535.

#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;
  entry_info.Entry_ID_CCSID = 0;
  strncpy(entry_info.Entry_ID,"FRED",entry_info.Entry_ID_Len);
  encrypt_data.Encr_Data_Len = 7;
  strncpy(encrypt_data.Encr_Data,"N1LJDTS",
            encrypt_data.Encr_Data_Len);
  encrypt_data.Encr_Data_CCSID = 65535;

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

}