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

618 lines
17 KiB
HTML
Raw 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>QsyAddValidationLstEntry()--Add 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 -->
<!--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>QsyAddValidationLstEntry()--Add Validation List Entry API</h2>
<div class="box" style="width: 80%;">
<br>
&nbsp;&nbsp;Syntax<br>
<pre>
#include &lt;qsyvldl.h&gt;
int QsyAddValidationLstEntry
(Qsy_Qual_Name_T *<em>Validation_Lst</em>,
Qsy_Entry_ID_Info_T *<em>Entry_ID</em>,
Qsy_Entry_Encr_Data_Info_T *<em>Encrypt_Data</em>,
Qsy_Entry_Data_Info_T *<em>Entry_Data</em>,
void *<em>Attribute_Info</em>);
</pre>
<br>
&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>QsyAddValidationLstEntry()</strong> 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.</p>
<p>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.</p>
<br>
<h3>Authorities</h3>
<dl>
<dt><em>Validation List Object</em></dt>
<dd>*USE and *ADD<br>
<br>
</dd>
<dt><em>Validation List Object Library</em></dt>
<dd>*EXECUTE</dd>
</dl>
<br>
<h3>Parameters</h3>
<dl>
<dt><strong>Validation_Lst</strong></dt>
<dd>(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:
<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>Entry_ID</strong></dt>
<dd>(Input) A pointer to the entry ID information. The format of the
Qsy_Entry_ID_Info_T structure is as follows:<br>
<br>
<table cellpadding="5" border>
<!-- 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. The special
value follows:
<table cellpadding="5">
<tr>
<td align="left" valign="top"><em>0</em></td>
<td align="left" valign="top">The default CCSID for the current user is
stored.</td>
</tr>
</table>
</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>Encrypt_Data</strong></dt>
<dd>(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:<br>
<br>
<table cellpadding="5" border>
<!-- 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 data to be encrypted and
stored in this validation list entry. Possible values are from 1 through
600.</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">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:<br>
<table cellpadding="5">
<tr>
<td align="left" valign="top"><em>0</em></td>
<td align="left" valign="top">The default CCSID for the current user is
stored.</td>
</tr>
</table>
</td>
</tr>
<tr>
<td align="left" valign="top">unsigned char</td>
<td align="left" valign="top">Encr_Data[]</td>
<td align="left" valign="top">The data to be encrypted before storing it in the
validation list entry.</td>
</tr>
</table>
<br>
</dd>
<dt><strong>Entry_Data</strong></dt>
<dd>(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:<br>
<br>
<table cellpadding="5" border>
<!-- 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 number of bytes of data to be stored in this
validation list entry. Possible values are from 1 through 1000.</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">An integer that represents the CCSID for the
data. Valid CCSID values are in the range 1 through 65535. The special value
follows:<br>
<table cellpadding="5">
<tr>
<td align="left" valign="top"><em>0</em></td>
<td align="left" valign="top">The default CCSID for the current user is
stored.</td>
</tr>
</table>
</td>
</tr>
<tr>
<td align="left" valign="top">unsigned char</td>
<td align="left" valign="top">Entry_Data[]</td>
<td align="left" valign="top">The data to be stored in the validation list
entry.</td>
</tr>
</table>
<br>
</dd>
<dt><strong>Attribute_Info</strong></dt>
<dd>(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:<br>
<br>
<table cellpadding="5" border>
<!-- cols="20 25 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 being added. 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>
<p>The format of the Qsy_Attr_Descr_T structure is as follows:</p>
<table cellpadding="5" border>
<!-- cols="15 20 65" -->
<tr>
<td align="left" valign="top">int</td>
<td align="left" valign="top">Attr_Location</td>
<td align="left" valign="top">Where the attribute should be 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&nbsp;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 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">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 value is:<br>
<table cellpadding="5">
<tr>
<td align="left" valign="top"><em>String value</em></td>
<td align="left" valign="top">Description</td>
</tr>
<tr>
<td align="left" valign="top"><em>QsyEncryptData</em></td>
<td align="left" valign="top">This is the attribute that is associated with the
data to encrypt.</td>
</tr>
</table>
</td>
</tr>
<tr>
<td align="left" valign="top">union</td>
<td align="left" valign="top">Attr_Other_Descr Res_1[32]</td>
<td align="left" valign="top">Reserved data. This value must be hexadecimal
zero.</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 describing the attribute
data.</td>
</tr>
<tr>
<td align="left" valign="top">union</td>
<td align="left" valign="top">Attr_Other_Data Res_1[32]</td>
<td align="left" valign="top">Reserved data. This value must be hexadecimal
zero.</td>
</tr>
</table>
<br>
<br>
<p>The format of the Attr_Data_Info union is as follows:</p>
<table cellpadding="5" border>
<!-- cols="20 20 60" -->
<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 Res_1[96]</td>
<td align="left" valign="top">Reserved data. The last 64 bytes must be
zero.</td>
</tr>
</table>
<br>
<br>
<p>The format of the Qsy_In_VLDL_T structure is as follows:</p>
<table cellpadding="5" border>
<!-- 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. The special
values follow:<br>
<table cellpadding="5">
<tr>
<td align="left" valign="top" nowrap><em>-1</em></td>
<td align="left" valign="top">No CCSID value is stored with the attribute. If
the attribute is QsyEncryptData, this value must be specified.</td>
</tr>
<tr>
<td align="left" valign="top"><em>0</em></td>
<td align="left" valign="top">The default CCSID for the current user is
stored.</td>
</tr>
</table>
</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 attribute
value. The length must be greater than 0. For the QsyEncryptData attribute, the
length must be 1.</td>
</tr>
<tr>
<td align="left" valign="top">union</td>
<td align="left" valign="top">Attr_Res 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 the value of the attribute
associated with the entry. For the QsyEncryptData attribute, the allowed values
follow:<br>
<br>
<table cellpadding="5">
<tr>
<td align="left" valign="top"><em>0 QSY_VFY_ONLY</em></td>
<td align="left" valign="top">The data to be encrypted can only be used to
verify an entry. This is the default.</td>
</tr>
<tr>
<td align="left" valign="top"><em>1 QSY_VFY_FIND</em></td>
<td align="left" valign="top">The data to be encrypted can be used to verify an
entry and can be returned on a find operation.</td>
</tr>
</table>
</td>
</tr>
</table>
</dd>
</dl>
<p>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.</p>
<p>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.</p>
<p>If the system value is set to 1 (Retain data), then the data to be encrypted
will be stored when the entry is added.</p>
<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>QsyAddValidationLstEntry()</strong> was
successful.<br>
<br>
</td>
</tr>
<tr>
<td align="left" valign="top"><em>-1</em> </td>
<td align="left" valign="top"><strong>QsyAddValidationLstEntry()</strong> was
not successful. The <em>errno</em> global variable is set to indicate the
error.<br>
<br>
</td>
</tr>
<tr>
<td align="left" valign="top" nowrap><em>-2</em> </td>
<td align="left" valign="top"><strong>QsyAddValidationLstEntry()</strong> was
successful, but the data to be encrypted was not stored.</td>
</tr>
</table>
<br>
<br>
<h3>Error Conditions</h3>
<p>If <strong>QsyAddValidationLstEntry()</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"><strong>3401</strong> </td>
<td align="left" valign="top">[EACCES]
<p>The current user does not have *USE and *ADD authorities 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"><strong>3406</strong> </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"><strong>3484</strong> </td>
<td align="left" valign="top">[EDAMAGE]
<p>The validation list object is damaged.</p>
</td>
</tr>
<tr>
<td align="left" valign="top"><strong>3457</strong> </td>
<td align="left" valign="top">[EEXIST]
<p>Specified entry already exists.</p>
</td>
</tr>
<tr>
<td align="left" valign="top"><strong>3021</strong> </td>
<td align="left" valign="top">[EINVAL]
<p>Parameter value is not valid.</p>
</td>
</tr>
<tr>
<td align="left" valign="top"><strong>3025</strong> </td>
<td align="left" valign="top">[ENOENT]
<p>The validation list object was not found.</p>
</td>
</tr>
<tr>
<td align="left" valign="top"><strong>3404</strong> </td>
<td align="left" valign="top">[ENOSPC]
<p>No space available.</p>
</td>
</tr>
<tr>
<td align="left" valign="top"><strong>3474</strong> </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 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.</p>
<pre>
#include &lt;qsyvldl.h&gt;
main()
{
#define VLD_LST &quot;WEBUSRS WEBLIB &quot;
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,&quot;FRED&quot;,entry_info.Entry_ID_Len);
encrypt_data.Encr_Data_Len = 7;
strncpy(encrypt_data.Encr_Data,&quot;N1LJDTS&quot;,
encrypt_data.Encr_Data_Len);
encrypt_data.Encr_Data_CCSID = 65535;
if (0 != QsyAddValidationLstEntry((Qsy_Qual_Name_T *)&amp;VLD_LST,
&amp;entry_info,
&amp;encrypt_data,
NULL,
NULL))
perror(&quot;QsyAddValidationLstEntry()&quot;);
}
</pre>
<br>
<hr>
API introduced: V4R1
<hr>
<table cellpadding="2" cellspacing="2" align="center">
<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>
</body>
</html>
Reference in New Issue View Git Blame Copy Permalink