friedkiwi/ibm-information-center
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity
master
ibm-information-center/dist/eclipse/plugins/i5OS.ic.apis_5.4.0.1/QSYFIVLA.htm

792 lines
21 KiB
HTML
Raw Permalink Blame History

<!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>QsyFindValidationLstEntryAttrs()--Find Validation List Entry Attributes
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>QsyFindValidationLstEntryAttrs()--Find Validation List Entry Attributes
API</h2>
<div class="box" style="width: 60%;">
<br>
&nbsp;&nbsp;Syntax
<pre>
#include &lt;qsyvldl.h&gt;
int QsyFindValidationLstEntryAttrs
(Qsy_Qual_Name_T *<em>Validation_Lst</em>,
Qsy_Entry_ID_Info_T *<em>Entry_ID</em>,
Qsy_Rtn_Vld_Lst_Ent_T *<em>Rtn_Entry</em>,
Qsy_Attr_Info_T *<em>Rtn_Attributes</em>);
</pre>
&nbsp;&nbsp;Service Program Name: QSYVLDL<br>
<!-- iddvc RMBR -->
<br>
&nbsp;&nbsp;Default Public Authority: *USE<br>
<!-- iddvc RMBR -->
<br>
&nbsp;&nbsp;Threadsafe: Yes<br>
<!-- iddvc RMBR -->
<br>
</div>
<p>The <strong>QsyFindValidationLstEntryAttrs()</strong> 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 <em>Rtn_Entry</em> parameter, and the information for
the attributes in the buffer that is pointed to by the <em>Rtn_Attributes</em>
parameter. To find an entry, there must be an exact match in the entry for the
value that is specified in the <em>Entry_ID</em> 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.</p>
<br>
<h3>Authorities</h3>
<dl>
<dt><em>Validation List Object</em></dt>
<dd>*USE<br>
<br>
</dd>
<dt><em>Validation List Object Library</em></dt>
<dd>*EXECUTE</dd>
</dl>
<p><strong>Note:</strong> 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
<em>Rtn_Entry</em> parameter.</p>
<br>
<h3>Parameters</h3>
<dl>
<dt><strong>Validation_Lst</strong></dt>
<dd>(Input)
<p>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:</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><a name="entry_id">Entry_ID</a></strong></dt>
<dd>(Input)
<p>A pointer to the entry ID information. 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 number of bytes of data that is provided as
the entry ID. Possible values are from 1 through 100.</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">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.</td>
</tr>
<tr>
<td align="left" valign="top">unsigned char</td>
<td align="left" valign="top">Entry_ID[]</td>
<td align="left" valign="top">The data that is used to identify this entry in
the validation list.</td>
</tr>
</table>
<br>
</dd>
<dt><strong>Rtn_Entry</strong></dt>
<dd>(Output)
<p>A pointer to the buffer where the 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. 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>
<td align="left" valign="top">Qsy_Entry_ID_Info_T</td>
<td align="left" valign="top">Entry_ID_Info</td>
<td align="left" valign="top">The entry ID information structure.</td>
</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>
<br>
</dd>
<dd>See the <a href="#entry_id">Entry_ID</a> parameter for the format of the
Qsy_Entry_ID_Info_T structure.<br>
<br>
<br>
</dd>
<dd>The format of the Qsy_Entry_Encr_Data_Info_T structure is as follows:<br>
<br>
<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>
<br>
<br>
</dd>
<dd>The format of the Qsy_Entry_Data_Info_T structure is as follows:<br>
<br>
<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>
<br>
</dd>
<dt><strong>Rtn_Attributes</strong></dt>
<dd>(Input) A pointer to a structure that indicates the attributes to return.
The format of the Qsy_Attr_Info_T structure is as follows:<br>
<br>
<table border cellpadding="5">
<!-- cols="25 20 55" -->
<tr>
<td align="left" valign="top">int</td>
<td align="left" valign="top">Number_Attrs</td>
<td align="left" valign="top">The number of attributes to be returned. This
value must be greater than 0.</td>
</tr>
<tr>
<td align="left" valign="top">char</td>
<td align="left" valign="top">Res_Align[12]</td>
<td align="left" valign="top">Reserved for boundary alignment.</td>
</tr>
<tr>
<td align="left" valign="top">Qsy_Attr_Descr_T</td>
<td align="left" valign="top">Attr_Descr[]</td>
<td align="left" valign="top">An array of attribute description
structures.</td>
</tr>
</table>
<br>
<br>
</dd>
<dd>The format of the Qsy_Attr_Descr_T structure is as follows:<br>
<br>
<table border cellpadding="5">
<!-- cols="25 20 55" -->
<tr>
<td align="left" valign="top">int</td>
<td align="left" valign="top">Attr_Location</td>
<td align="left" valign="top">Where the attribute is stored. The allowed value
follows:<br>
<table cellpadding="5">
<tr>
<td align="left" valign="top"><em>0 QSY_IN_VLDL</em></td>
<td align="left" valign="top">The attribute is stored in the validation list
object.</td>
</tr>
</table>
</td>
</tr>
<tr>
<td align="left" valign="top">int</td>
<td align="left" valign="top">Attr_Type</td>
<td align="left" valign="top">The type of attribute. The allowed value
follows:<br>
<table cellpadding="5">
<tr>
<td align="left" valign="top"><em>0 QSY_SYSTEM_ATTR</em></td>
<td align="left" valign="top">This is a system-defined attribute.</td>
</tr>
</table>
</td>
</tr>
<tr>
<td align="left" valign="top">union</td>
<td align="left" valign="top">Attr_Res<br>
&nbsp;&nbsp;&nbsp;Res_1[8]</td>
<td align="left" valign="top">Reserved data. This value must be hexadecimal
zero.<br>
<br>
</td>
</tr>
<tr>
<td align="left" valign="top">char *</td>
<td align="left" valign="top">Attr_ID</td>
<td align="left" valign="top">The ID of the attribute. For system-defined
attributes, the allowed values are:</td>
</tr>
<tr>
<td align="left" valign="top">&nbsp;<br>
</td>
<td align="left" valign="top">String value</td>
<td align="left" valign="top">Description<br>
<br>
</td>
</tr>
<tr>
<td align="left" valign="top">&nbsp;<br>
</td>
<td align="left" valign="top">QsyEncryptData</td>
<td align="left" valign="top">This is the attribute that is associated with the
data to encrypt.<br>
<br>
</td>
</tr>
<tr>
<td align="left" valign="top">&nbsp;<br>
</td>
<td align="left" valign="top">QsyX509Cert</td>
<td align="left" valign="top">This is the X.509 certificate attribute for the
entry.<br>
<br>
</td>
</tr>
<tr>
<td align="left" valign="top">&nbsp;<br>
</td>
<td align="left" valign="top">QsyEntryUsage</td>
<td align="left" valign="top">This is the entry usage information
attribute.<br>
<br>
</td>
</tr>
<tr>
<td align="left" valign="top">union</td>
<td align="left" valign="top">Attr_Other_Descr<br>
&nbsp;&nbsp;&nbsp;Res_1[32]</td>
<td align="left" valign="top">Reserved data. This value must be hexadecimal
zero.<br>
<br>
</td>
</tr>
<tr>
<td align="left" valign="top">union</td>
<td align="left" valign="top">Attr_Data_Info</td>
<td align="left" valign="top">The information that describes the attribute
data.<br>
<br>
</td>
</tr>
<tr>
<td align="left" valign="top">union</td>
<td align="left" valign="top">Attr_Other_Data<br>
&nbsp;&nbsp;&nbsp;Res_1[32]</td>
<td align="left" valign="top">Reserved data. This value must be hexadecimal
zero.</td>
</tr>
</table>
<br>
<br>
</dd>
<dd>The format of the Attr_Data_Info union is as follows:<br>
<br>
<table border cellpadding="5">
<!-- cols="15 20 65" -->
<tr>
<td align="left" valign="top">Qsy_In_VLDL_T</td>
<td align="left" valign="top">Attr_VLDL</td>
<td align="left" valign="top">The attribute data information for an attribute
that is stored in the validation list object.</td>
</tr>
<tr>
<td align="left" valign="top">union</td>
<td align="left" valign="top">Attr_In_Other<br>
&nbsp;&nbsp;&nbsp;Res_1[96]</td>
<td align="left" valign="top">Reserved data. The last 64 bytes must be
hexadecimal zero.</td>
</tr>
</table>
<br>
<br>
</dd>
<dd>The format of the Qsy_In_VLDL_T structure is as follows:<br>
<br>
<table border cellpadding="5">
<!-- cols="15 20 65" -->
<tr>
<td align="left" valign="top">int</td>
<td align="left" valign="top">Attr_CCSID</td>
<td align="left" valign="top">An integer that represents the CCSID for the
attribute. Valid CCSID values are in the range -1 through 65535. This value is
not used.</td>
</tr>
<tr>
<td align="left" valign="top">int</td>
<td align="left" valign="top">Attr_Len</td>
<td align="left" valign="top">The number of bytes of data in the buffer to
return the attribute value. The minimum length is 12.</td>
</tr>
<tr>
<td align="left" valign="top">union</td>
<td align="left" valign="top">Attr_Res<br>
&nbsp;&nbsp;&nbsp;Res_1[8]</td>
<td align="left" valign="top">Reserved data. This value must be hexadecimal
zero.</td>
</tr>
<tr>
<td align="left" valign="top">void *</td>
<td align="left" valign="top">Attr_Value</td>
<td align="left" valign="top">A pointer to a Qsy_Rtn_VLDL_Attr_T structure in
which to return the attribute.</td>
</tr>
</table>
<br>
<br>
</dd>
<dd>The format of the Qsy_Rtn_VLDL_Attr_T structure is as follows:<br>
<br>
<table border cellpadding="5">
<!-- cols="15 20 65" -->
<tr>
<td align="left" valign="top">int</td>
<td align="left" valign="top">Bytes_Returned</td>
<td align="left" valign="top">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.</td>
</tr>
<tr>
<td align="left" valign="top">int</td>
<td align="left" valign="top">Bytes_Available</td>
<td align="left" valign="top">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.</td>
</tr>
<tr>
<td align="left" valign="top">int</td>
<td align="left" valign="top">Attr_Len</td>
<td align="left" valign="top">The length (in bytes) of the returned
attribute.</td>
</tr>
<tr>
<td align="left" valign="top">unsigned int</td>
<td align="left" valign="top">Attr_CCSID</td>
<td align="left" valign="top">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.</td>
</tr>
<tr>
<td align="left" valign="top">unsigned char</td>
<td align="left" valign="top">Attr_Data[]</td>
<td align="left" valign="top">The value of the returned attribute.</td>
</tr>
</table>
<br>
<br>
</dd>
<dd>The format of the Qsy_Rtn_Entry_Usage_Attr_T structure is as follows:<br>
<br>
<table border cellpadding="5">
<!-- cols="15 25 60" -->
<tr>
<td align="left" valign="top">char</td>
<td align="left" valign="top">Create_Date[8]</td>
<td align="left" valign="top">The date the entry was added to the validation
list.</td>
</tr>
<tr>
<td align="left" valign="top">char</td>
<td align="left" valign="top">Last_Used_Date[8]</td>
<td align="left" valign="top">The date of the last successful verify.</td>
</tr>
<tr>
<td align="left" valign="top">char</td>
<td align="left" valign="top">Encr_Data_Chg_Date[8]</td>
<td align="left" valign="top">The date the encrypted data was last
changed.</td>
</tr>
<tr>
<td align="left" valign="top">int</td>
<td align="left" valign="top">Not_Valid_Verify_Count</td>
<td align="left" valign="top">The number of times that incorrect encrypted data
has been specified on a verify since the last successful verify.</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"><strong>QsyFindValidationLstEntryAttrs()</strong>
was successful. The return value points to the entry. The return attribute
points to the attribute list.<br>
<br>
</td>
</tr>
<tr>
<td align="left" valign="top" nowrap><em>-1</em> </td>
<td align="left" valign="top"><strong>QsyFindValidationLstEntryAttrs()</strong>
was not successful. The <em>errno</em> global variable is set to indicate the
error.</td>
</tr>
</table>
<br>
<br>
<h3>Error Conditions</h3>
<p>If <strong>QsyFindValidationLstEntryAttrs()</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>Specified entry does not exist.</p>
</td>
</tr>
<tr>
<td align="left" valign="top"><em>3404</em></td>
<td align="left" valign="top">[ENOSPC]
<p>No space available.</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>
<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 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.</p>
<pre>
#include &lt;stdlib.h&gt;
#include &lt;qsyvldl.h&gt;
#include &lt;errno.h&gt;
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 *)&amp;encr_attr;
/* Try to find an entry for 'FRED'. */
if (0 == QsyFindValidationLstEntryAttrs(
(Qsy_Qual_Name_T *)&amp;VLD_LST,
&amp;rtn_ent.Entry_ID_Info,
&amp;rtn_ent,
(Qsy_Attr_Info_T *)&amp;rtn_attr))
{ /* Entry was found */
.
.
.
(process the entry)
.
.
.
}
else /* Error on find of entry. */
perror("Find of validation list entry");
}
</pre>
<br>
<hr>
API introduced: V4R2
<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>
Reference in New Issue View Git Blame Copy Permalink