620 lines
17 KiB
HTML
620 lines
17 KiB
HTML
<!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>QsyChangeValidationLstEntry()--Change 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 -->
|
|
<!-- Edited by Kersten Jan 02 -->
|
|
<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>QsyChangeValidationLstEntry()--Change Validation List Entry API</h2>
|
|
|
|
<div class="box" style="width: 70%;">
|
|
<br>
|
|
Syntax<br>
|
|
<pre>
|
|
#include <qsyvldl.h>
|
|
|
|
int QsyChangeValidationLstEntry
|
|
(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>
|
|
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>QsyChangeValidationLstEntry()</strong> function changes an entry
|
|
in a validation list object. The data to be encrypted, the entry data values,
|
|
and some of the entry attributes may be changed.</p>
|
|
|
|
<p>To identify an entry to be changed, 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 allow you to change an entry where the entry ID is "SMITH" and the length is 7.</p>
|
|
|
|
<p>Conversions are not done on any data when entries are changed. The CCSID
|
|
values are stored as part of the record, to be available to the user of the
|
|
API, but are not used when the entry is changed.</p>
|
|
|
|
<br>
|
|
<h3>Authorities</h3>
|
|
|
|
<dl>
|
|
<dt><em>Validation List Object</em></dt>
|
|
|
|
<dd>*USE and *UPD<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)
|
|
|
|
<p>A pointer to the qualified object name of the validation list that contains
|
|
the entry to change. 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>Entry_ID</strong></dt>
|
|
|
|
<dd>(Input)
|
|
|
|
<p>A pointer to the entry ID information. The Qsy_Entry_ID_Info_T structure is
|
|
as follows:</p>
|
|
|
|
<br>
|
|
<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 0 through 65535. This field is
|
|
not used to change 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>
|
|
<br>
|
|
</dd>
|
|
|
|
<dt><strong>Encrypt_Data</strong></dt>
|
|
|
|
<dd>(Input)
|
|
|
|
<p>A pointer to the data that is associated with the entry ID. The data is
|
|
encrypted by the system when it is stored. If the pointer is NULL, the
|
|
encrypted data that is associated with the entry ID is not changed. 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 data to be encrypted and
|
|
stored in this validation list entry. Possible values are from 0 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>
|
|
|
|
<p>If Encr_Data_Len is 0, any encrypted data that is associated with the entry
|
|
ID will be removed.</p>
|
|
</dd>
|
|
|
|
<dt><strong>Entry_Data</strong></dt>
|
|
|
|
<dd>(Input)
|
|
|
|
<p>A pointer to the data information that is associated with the entry ID. If
|
|
the pointer is NULL, the data that is associated with the entry ID is not
|
|
changed. 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 number of bytes of data to be stored in this
|
|
validation list entry. Possible values are from 0 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>
|
|
|
|
<p>If the Entry_Data_Length is 0, any data that is associated with the entry ID
|
|
will be removed.</p>
|
|
</dd>
|
|
|
|
<dt><strong>Attribute_Info</strong></dt>
|
|
|
|
<dd>(Input)
|
|
|
|
<p>A pointer to a structure that contains attribute information that is
|
|
associated with the entry ID. If the pointer is NULL, the attributes associated
|
|
with the entry ID are not changed. The format of the Qsy_Attr_Info_T structure
|
|
is as follows:</p>
|
|
|
|
<table border cellpadding="5">
|
|
<!-- cols="20 20 60" -->
|
|
<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 changed. 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 border cellpadding="5">
|
|
<!-- 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:
|
|
|
|
<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 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:</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td align="left" valign="top"> </td>
|
|
<td align="left" valign="top">String value</td>
|
|
<td align="left" valign="top">Description</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td align="left" valign="top"> </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. This attribute can only be changed if the Encrypt_Data
|
|
parameter is not NULL.</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 that describes 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_T union is as follows:</p>
|
|
|
|
<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 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 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. 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 is assumed.</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 or equal to 0. If a length of 0 is
|
|
specified, the attribute is removed from the entry. For the QsyEncryptData
|
|
attribute, the maximum length is 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">Pointer to the value of the attribute associated
|
|
with the entry. For the QsyEncryptData attribute, the allowed values
|
|
follow:<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>
|
|
|
|
<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. If the system value is
|
|
set to 0 (Do not retain data), the entry will be changed, 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 changed, 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 changed.</p>
|
|
</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>QsyChangeValidationLstEntry()</strong>
|
|
was successful.</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td align="left" valign="top"><em>-1</em></td>
|
|
<td align="left" valign="top"><strong>QsyChangeValidationLstEntry()</strong>
|
|
was not successful. The <em>errno</em> global variable is set to indicate the
|
|
error.</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td align="left" valign="top"><em>-2</em></td>
|
|
<td align="left" valign="top"><strong>QsyChangeValidationLstEntry()</strong>
|
|
was successful, but the data to be encrypted was not stored.</td>
|
|
</tr>
|
|
</table>
|
|
|
|
<br>
|
|
|
|
|
|
<h3>Error Conditions</h3>
|
|
|
|
<p>If <strong>QsyChangeValidationLstEntry()</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 and *UPD 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"><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>
|
|
<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 changes an entry for a user named FRED in the
|
|
validation list object WEBUSRS. FRED's encrypted data (password) and the CCSID
|
|
for the encrypted data are being changed, but not any other data.</p>
|
|
|
|
<pre>
|
|
#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;
|
|
strncpy(entry_info.Entry_ID,"FRED",entry_info.Entry_ID_Len);
|
|
encrypt_data.Encr_Data_Len = 7;
|
|
encrypt_data.Encr_Data_CCSID = 37;
|
|
strncpy(encrypt_data.Encr_Data,"MSN1TJG",
|
|
encrypt_data.Encr_Data_Len);
|
|
|
|
if (0 != QsyChangeValidationLstEntry(
|
|
(Qsy_Qual_Name_T *)&VLD_LST,
|
|
&entry_info,
|
|
&encrypt_data,
|
|
NULL,
|
|
NULL))
|
|
perror("QsyChangeValidationLstEntry()");
|
|
|
|
}
|
|
|
|
</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>
|
|
|