<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"> <html> <head> <meta http-equiv="Content-Type" content="text/html; charset=utf-8"> <meta name="Copyright" content="Copyright (c) 2006 by IBM Corporation"> <title>QsyFindFirstValidationLstEntry()--Find First Validation List Entry API</title> <!-- Begin Header Records ========================================== --> <!-- All rights reserved. Licensed Materials Property of IBM --> <!-- US Government Users Restricted Rights --> <!-- Use, duplication or disclosure restricted by --> <!-- GSA ADP Schedule Contract with IBM Corp. --> <!-- Sec SCRIPT A converted by B2H R4.1 (346) (CMS) by V2KEA304 --> <!-- at RCHVMW2 on 17 Feb 1999 at 11:05:09 --> <!-- Change History: --> <!-- YYMMDD USERID Change description --> <!-- Edited by Kersten Jan 02 --> <!--End Header Records --> <link rel="stylesheet" type="text/css" href="../rzahg/ic.css"> </head> <body> <a name="Top_Of_Page"></a> <!-- Java sync-link --> <script type="text/javascript" language="Javascript" src="../rzahg/synch.js"> </script> <h2>QsyFindFirstValidationLstEntry()--Find First Validation List Entry API</h2> <div class="box" style="width: 70%;"> <br> Syntax<br> <pre> #include <qsyvldl.h> int QsyFindFirstValidationLstEntry (Qsy_Qual_Name_T *<em>Validation_Lst</em>, Qsy_Rtn_Vld_Lst_Ent_T *<em>First_Entry</em>); </pre> <br> Service Program Name: QSYVLDL<br> <!-- iddvc RMBR --> <br> Default Public Authority: *USE<br> <!-- iddvc RMBR --> <br> Threadsafe: Yes<br> <!-- iddvc RMBR --> <br> </div> <p>The <strong>QsyFindFirstValidationLstEntry()</strong> function finds the first entry in a validation list object. The function then returns the information for the first entry in the buffer that is pointed to by the <em>First_Entry</em> parameter. The entries are stored in hexadecimal sort sequence, so the first entry will be the one where the entry ID has the smallest hexadecimal value.<br> </p> <h3>Authorities</h3> <dl> <dt><em>Validation List Object</em></dt> <dd>*USE<br> </dd> <dt><em>Validation List Object Library</em></dt> <dd>*EXECUTE<br> </dd> </dl> <p><strong>Note:</strong> If the QsyEncryptData attribute is set to QSY_VFY_FIND_E (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 <em>First_Entry</em> parameter.<br> </p> <h3>Parameters</h3> <dl> <dt><strong>Validation_Lst</strong></dt> <dd>(Input) <p>A pointer to the qualified object name of the validation list to find the first entry in. 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:</p> <table cellpadding="5"> <!-- cols="15 85" --> <tr> <td align="left" valign="top"><em>*CURLIB</em></td> <td align="left" valign="top">The current library is used to locate the validation list. If there is no current library, QGPL (general purpose library) is used.</td> </tr> <tr> <td align="left" valign="top"><em>*LIBL</em></td> <td align="left" valign="top">The library list is used to locate the validation list.</td> </tr> </table> <br> </dd> <dt><strong>First_Entry</strong></dt> <dd>(Output) <p>A pointer to the buffer where the first entry information is placed. The buffer must be allocated to the size of the <em>Qsy_Rtn_Vld_Lst_Ent_T</em> structure or the results will be unpredictable.</p> <p>The format of the <em>Qsy_Rtn_Vld_Lst_Ent_T</em> structure is as follows:</p> <table border cellpadding="5"> <!-- cols="30 20 50" --> <tr> <th align="left" valign="top">Qsy_Entry_ID_Info_T</th> <th align="left" valign="top">Entry_ID_Info</th> <th align="left" valign="top">The entry ID information structure.</th> </tr> <tr> <td align="left" valign="top">Qsy_Entry_Encr_Data_Info_T</td> <td align="left" valign="top">Encr_Data_Info</td> <td align="left" valign="top">The data to be encrypted information structure.</td> </tr> <tr> <td align="left" valign="top">Qsy_Entry_Data_Info_T</td> <td align="left" valign="top">Entry_Data_Info</td> <td align="left" valign="top">The entry data information structure.</td> </tr> <tr> <td align="left" valign="top">char</td> <td align="left" valign="top">Reserved[4]</td> <td align="left" valign="top">This is an ignored field.</td> </tr> <tr> <td align="left" valign="top">void *</td> <td align="left" valign="top">Entry_More_Info</td> <td align="left" valign="top">A pointer to additional information. This pointer is currently set to NULL.</td> </tr> </table> <p>The format of the Qsy_Entry_ID_Info_T structure is as follows:</p> <table border cellpadding="5"> <!-- cols="15 20 65" --> <tr> <td align="left" valign="top">int</td> <td align="left" valign="top">Entry_ID_Len</td> <td align="left" valign="top">The length of the entry ID.</td> </tr> <tr> <td align="left" valign="top">unsigned int</td> <td align="left" valign="top">Entry_ID_CCSID</td> <td align="left" valign="top">The CCSID associated with the entry ID.</td> </tr> <tr> <td align="left" valign="top">unsigned char</td> <td align="left" valign="top">Entry_ID[100]</td> <td align="left" valign="top">The entry ID.</td> </tr> </table> <p>The format of the Qsy_Entry_Encr_Data_Info_T structure is as follows:</p> <table border cellpadding="5"> <!-- cols="15 20 65" --> <tr> <td align="left" valign="top">int</td> <td align="left" valign="top">Encr_Data_Len</td> <td align="left" valign="top">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.</td> </tr> <tr> <td align="left" valign="top">unsigned int</td> <td align="left" valign="top">Encr_Data_CCSID</td> <td align="left" valign="top">The CCSID associated with the encrypted data.</td> </tr> <tr> <td align="left" valign="top">unsigned char</td> <td align="left" valign="top">Encr_Data[600]</td> <td align="left" valign="top">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.</td> </tr> </table> <p>The format of the Qsy_Entry_Data_Info_T structure is as follows:</p> <table border cellpadding="5"> <!-- cols="15 20 65" --> <tr> <td align="left" valign="top">int</td> <td align="left" valign="top">Entry_Data_Len</td> <td align="left" valign="top">The length of the entry data.</td> </tr> <tr> <td align="left" valign="top">unsigned int</td> <td align="left" valign="top">Entry_Data_CCSID</td> <td align="left" valign="top">The CCSID associated with the entry data.</td> </tr> <tr> <td align="left" valign="top">unsigned char</td> <td align="left" valign="top">Entry_Data[1000]</td> <td align="left" valign="top">The entry data.</td> </tr> </table> </dd> </dl> <br> <h3>Return Value</h3> <table cellpadding="5"> <!-- cols="5 95" --> <tr> <td align="left" valign="top"><em>0</em></td> <td align="left" valign="top">QsyFindFirstValidationLstEntry() was successful. The return value points to the entry.</td> </tr> <tr> <td align="left" valign="top" nowrap><em>-1</em></td> <td align="left" valign="top">QsyFindFirstValidationLstEntry() was not successful. The <em>errno</em> global variable is set to indicate the error.</td> </tr> </table> <br> <h3>Error Conditions</h3> <p>If <strong>QsyFindFirstValidationLstEntry()</strong> is not successful, <em>errno</em> indicates one of the following errors:</p> <table cellpadding="5"> <!-- cols="10 90" --> <tr> <td align="left" valign="top"><em>3401</em></td> <td align="left" valign="top">[EACCES] <p>The current user does not have *USE authority to the validation list object, or does not have *EXECUTE authority to the validation list object library.</p></td> </tr> <tr> <td align="left" valign="top"><em>3406</em></td> <td align="left" valign="top">[EAGAIN] <p>The validation list object is currently locked by another process.</p></td> </tr> <tr> <td align="left" valign="top"><em>3484</em></td> <td align="left" valign="top">[EDAMAGE] <p>The validation list object is damaged.</p></td> </tr> <tr> <td align="left" valign="top"><em>3021</em></td> <td align="left" valign="top">[EINVAL] <p>Parameter value is not valid.</p></td> </tr> <tr> <td align="left" valign="top"><em>3025</em></td> <td align="left" valign="top">[ENOENT] <p>The validation list object was not found.</p></td> </tr> <tr> <td align="left" valign="top"><em>3026</em></td> <td align="left" valign="top">[ENOREC] <p>There are no entries in the validation list object.</p></td> </tr> <tr> <td align="left" valign="top"><em>3474</em></td> <td align="left" valign="top">[EUNKNOWN] <p>Unknown system state. Check the job log for a CPF9872 message.</p></td> </tr> </table> <br> <h3>Example</h3> <p>See <a href="../apiref/aboutapis.htm#codedisclaimer">Code disclaimer information</a> for information pertaining to code examples.</p> <p>The following example finds all the entries in the validation list object WEBUSRS.</p> <pre> #include <qsyvldl.h> #include <errno.h> main() { #define VLD_LST "WEBUSRS WEBLIB " Qsy_Rtn_Vld_Lst_Ent_T entry_1; Qsy_Rtn_Vld_Lst_Ent_T entry_2; Qsy_Rtn_Vld_Lst_Ent_T *input_info, *output_info, *temp; Qsy_Entry_ID_Info_T *input_entry; short int i; int rtn_errno; /* Initialize pointers to input and output buffers. */ output_info = addr(entry_1); input_info = addr(entry_2); /* Get the first entry in the validation list. */ rtn_errno = QsyFindFirstValidationLstEntry( (Qsy_Qual_Name_T *)&VLD_LST, output_info)) while (0 == rtn_errno) { /* Process all the entries in the validation list. */ . . . (process the entry) . . . /* Switch the pointers to the buffers so that the output from */ /* the last find operation is used as input to the 'find-next' /* operation. */ temp = output_info; output_info = input_info; input_info = temp; /* Find the next entry. */ rtn_errno = QsyFindNextValidationLstEntry( (Qsy_Qual_Name_T *)&VLD_LST, &input_info->Entry_ID_Info, output_info)) } /* Check if an error occurred. */ if (0 != rtn_errno && ENOREC != errno) perror("Find of validation list entry"); } </pre> <br> <hr> API introduced: V4R1 <hr> <center> <table cellpadding="2" cellspacing="2"> <tr align="center"> <td valign="middle" align="center"><a href="#Top_Of_Page">Top</a> | <a href= "sec.htm">Security APIs</a> | <a href="aplist.htm">APIs by category</a></td> </tr> </table> </center> </body> </html>