QsyFindValidationLstEntryAttrs()--Find Validation List Entry Attributes API

 #include <qsyvldl.h>

 int QsyFindValidationLstEntryAttrs
        (Qsy_Qual_Name_T           *Validation_Lst,
         Qsy_Entry_ID_Info_T       *Entry_ID,
         Qsy_Rtn_Vld_Lst_Ent_T     *Rtn_Entry,
         Qsy_Attr_Info_T           *Rtn_Attributes);  
 

The QsyFindValidationLstEntryAttrs() function finds an entry in a validation list object, and the attributes associated with the entry. The function then returns the information for the entry in the buffer that is pointed to by the Rtn_Entry parameter, and the information for the attributes in the buffer that is pointed to by the Rtn_Attributes parameter. To find an entry, 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 find an entry where the entry ID is "SMITH " and the length is 7.

Authorities

Validation List Object

*USE

Validation List Object Library

*EXECUTE

Note: If the QsyEncryptData attribute is set to QSY_VFY_FIND (1), then the user must have *USE, *ADD, and *UPD authority to the validation list to get the data to be encrypted returned in the Rtn_Entry parameter.

Parameters

Validation_Lst

(Input)

A pointer to the qualified object name of the validation list in which to find the entry. 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. This value is not used to find the entry.
unsigned char	Entry_ID[]	The data that is used to identify this entry in the validation list.

Rtn_Entry

(Output)

A pointer to the buffer where the entry information is placed. The buffer must be allocated to the size of the Qsy_Rtn_Vld_Lst_Ent_T structure or the results will be unpredictable. The format of the Qsy_Rtn_Vld_Lst_Ent_T structure is as follows:

Qsy_Entry_ID_Info_T	Entry_ID_Info	The entry ID information structure.
Qsy_Entry_Encr_Data_Info_T	Encr_Data_Info	The data to be encrypted information structure.
Qsy_Entry_Data_Info_T	Entry_Data_Info	The entry data information structure
char	Reserved[4]	This is an ignored field.
void *	Entry_More_Info	A pointer to additional information. This pointer is currently set to NULL.

See the Entry_ID parameter for the format of the Qsy_Entry_ID_Info_T structure.

The format of the Qsy_Entry_Encr_Data_Info_T structure is as follows:

int	Encr_Data_Len	The number of bytes of encrypted data that is stored in this validation list entry. If the QsyEncryptData attribute is 0 or the QRETSVRSEC system value is '0', the length will always be 0.
unsigned int	Encr_Data_CCSID	The CCSID associated with the encrypted data.
unsigned char	Encr_Data[600]	If the QsyEncryptData attribute is 1 and the QRETSVRSEC system value is '1', then the encrypted data that is stored in the entry will be decrypted and returned in this field. If the QsyEncryptData attribute is 0 or the QRETSVRSEC system value is '0', then the encrypted data cannot be returned, and the contents of this field are unpredictable.

The format of the Qsy_Entry_Data_Info_T structure is as follows:

int	Entry_Data_Len	The length of the entry data.
unsigned int	Entry_Data_CCSID	The CCSID associated with the entry data.
unsigned char	Entry_Data[1000]	The entry data.

Rtn_Attributes

(Input) A pointer to a structure that indicates the attributes to return. The format of the Qsy_Attr_Info_T structure is as follows:

int	Number_Attrs	The number of attributes to be returned. 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 is 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 values are:
	String value	Description
	QsyEncryptData	This is the attribute that is associated with the data to encrypt.
	QsyX509Cert	This is the X.509 certificate attribute for the entry.
	QsyEntryUsage	This is the entry usage information attribute.
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 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 hexadecimal 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. This value is not used.
int	Attr_Len	The number of bytes of data in the buffer to return the attribute value. The minimum length is 12.
union	Attr_Res    Res_1[8]	Reserved data. This value must be hexadecimal zero.
void *	Attr_Value	A pointer to a Qsy_Rtn_VLDL_Attr_T structure in which to return the attribute.

The format of the Qsy_Rtn_VLDL_Attr_T structure is as follows:

int	Bytes_Returned	The number of bytes of data that is returned to the user in the attribute buffer. This is the lesser of the number of bytes available to be returned and Attr_Len in Qsy_In_VLDL_T.
int	Bytes_Available	The number of bytes of data that is available to be returned to the user in the attribute buffer. If all data is returned, bytes available is the same as the number of bytes returned. If the bytes available is 12, then the specified attribute is not defined for this entry.
int	Attr_Len	The length (in bytes) of the returned attribute.
unsigned int	Attr_CCSID	An integer that represents the CCSID for the attribute. Valid CCSID values are in the range 0 through 65535. This value is the CCSID value that was specified when the attribute was added or changed. If the value is 0, then no CCSID value was stored with the attribute.
unsigned char	Attr_Data[]	The value of the returned attribute.

The format of the Qsy_Rtn_Entry_Usage_Attr_T structure is as follows:

char	Create_Date[8]	The date the entry was added to the validation list.
char	Last_Used_Date[8]	The date of the last successful verify.
char	Encr_Data_Chg_Date[8]	The date the encrypted data was last changed.
int	Not_Valid_Verify_Count	The number of times that incorrect encrypted data has been specified on a verify since the last successful verify.

Return Value

Error Conditions

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

Example

See Code disclaimer information for information pertaining to code examples.

The following example finds an entry for a user named FRED in the validation list object WEBUSRS, and returns the attribute that is associated with the encrypted data field.

#include <stdlib.h>
#include <qsyvldl.h>
#include <errno.h>

main()
{
  #define VLD_LST  "WEBUSRS   WEBLIB    "
  Qsy_Rtn_Vld_Lst_Ent_T   rtn_ent;
  struct {
    Qsy_Attr_Info_T       attr_info;
    Qsy_Attr_Desc_T       attr_desc;
  } rtn_attr;
  struct {
    Qsy_Rtn_VLDL_Attr_T   encr_info;
    char                  encr_val;
  } encr_attr;
  Qsy_Entry_ID_Info_T    *input_entry;

  /* Set up entry ID to find.                                       */
  strncpy(rtn_ent.Entry_ID_Info.Entry_ID,"FRED",4);
  rtn_ent.Entry_ID_Info.Entry_ID_Len = 4;

  /* Set up the attribute information.                              */
                                  /* Initialize reserved fields.    */
  memset(rtn_attr.attr_desc.Attr_Res.Res_1,
         0,
         sizeof(rtn_attr.attr_desc.Attr_Res.Res_1));
  memset(rtn_attr.attr_desc.Attr_Other_Descr.Res_1,
         0,
         sizeof(rtn_attr.attr_desc.Attr_Other_Descr.Res_1));
  memset(rtn_attr.attr_desc.Attr_Data_Info.Attr_In_Other.Res_1,
         0,
         sizeof(rtn_attr.attr_desc.Attr_Data_Info.Attr_In_Other.Res_1));
  memset(rtn_attr.attr_desc.Attr_Other_Data.Res_1,
         0,
         sizeof(rtn_attr.attr_desc.Attr_Other_Data.Res_1));

                                  /* Set number of attrs.           */
  rtn_attr.attr_info.Numbers_Attrs = 1;
                                  /* Set location of attribute.     */
  rtn_attr.attr_desc.Attr_Location = QSY_IN_VLDL;
                                  /* Set attribute type.            */
  rtn_attr.attr_desc.Attr_Type = QSY_SYSTEM_ATTR;
                                  /* Set attribute type.            */
  rtn_attr.attr_desc.Attr_ID = (char *)QSY_ENCRYPT_DATA;
                                  /* Set length to retrieve.        */
  rtn_attr.attr_desc.Attr_Data_Info.Attr_VLDL.Attr_Len =
                                 sizeof(encr_attr);
                                  /* Set CCSID value.               */
  rtn_attr.attr_desc.Attr_Data_Info.Attr_VLDL.Attr_CCSID = -1;
                                  /* Set pointer to return buffer   */
  rtn_attr.attr_desc.Attr_Data_Info.Attr_VLDL.Attr_Value =
    (void *)&encr_attr;

  /* Try to find an entry for 'FRED'.                               */
  if (0 == QsyFindValidationLstEntryAttrs(
                     (Qsy_Qual_Name_T *)&VLD_LST,
                     &rtn_ent.Entry_ID_Info,
                     &rtn_ent,
                     (Qsy_Attr_Info_T *)&rtn_attr))
  { /* Entry was found                                              */
          .
          .
          .
     (process the entry)
          .
          .
          .
  }
  else /* Error on find of entry.                                   */
    perror("Find of validation list entry");

}