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/qgldcpyvl.htm

646 lines
24 KiB
HTML
Raw Permalink Normal View History

Add readme and dist folders
2024-04-02 14:02:31 +00:00
<!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>Copy Validation List To Directory (QGLDCPYVL) 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. -->
<!-- Created for V5R4 on 040427 -->
<!-- Change history: -->
<!-- 040426 JAM New API (XPF DCR 99858) -->
<!-- 050505 JAM Update for APAR SE20094 -->
<!-- Added optional alternate CCSID parameter -->
<!-- and Entry Exists Action (7/26/2005) -->
<!-- End Header Records -->
<link rel="stylesheet" type="text/css" href="../rzahg/ic.css">
</head>
<body>
<!-- Java sync-link -->
<script type="text/javascript" language="Javascript" src="../rzahg/synch.js">
</script>
<a name="Top_Of_Page"></a>
<h2><img src="delta.gif" alt="Start of change">Copy Validation List To Directory (QGLDCPYVL) API</h2>
<div class="box" style="width: 90%;">
<br>
&nbsp;&nbsp;Required Parameter Group:<br>
<br>
<table width="100%">
<tr>
<td align="center" valign="top" width="10%">1</td>
<td align="left" valign="top" width="50%">Qualified validation list name</td>
<td align="left" valign="top" width="20%">Input</td>
<td align="left" valign="top" width="20%">Char(20)</td>
</tr>
<tr>
<td align="center" valign="top" width="10%">2</td>
<td align="left" valign="top" width="50%">Bind distinguished name</td>
<td align="left" valign="top" width="20%">Input</td>
<td align="left" valign="top" width="20%">Char(*)</td>
</tr>
<tr>
<td align="center" valign="top" width="10%">3</td>
<td align="left" valign="top" width="50%">Length of bind distinguished name</td>
<td align="left" valign="top" width="20%">Input</td>
<td align="left" valign="top" width="20%">Binary(4)</td>
</tr>
<tr>
<td align="center" valign="top" width="10%">4</td>
<td align="left" valign="top" width="50%">Bind password</td>
<td align="left" valign="top" width="20%">Input</td>
<td align="left" valign="top" width="20%">Char(*)</td>
</tr>
<tr>
<td align="center" valign="top" width="10%">5</td>
<td align="left" valign="top" width="50%">Length of bind password</td>
<td align="left" valign="top" width="20%">Input</td>
<td align="left" valign="top" width="20%">Binary(4)</td>
</tr>
<tr>
<td align="center" valign="top" width="10%">6</td>
<td align="left" valign="top" width="50%">Parent distinguished name</td>
<td align="left" valign="top" width="20%">Input</td>
<td align="left" valign="top" width="20%">Char(*)</td>
</tr>
<tr>
<td align="center" valign="top" width="10%">7</td>
<td align="left" valign="top" width="50%">Length of parent distinguished name</td>
<td align="left" valign="top" width="20%">Input</td>
<td align="left" valign="top" width="20%">Binary(4)</td>
</tr>
<tr>
<td align="center" valign="top" width="10%">8</td>
<td align="left" valign="top" width="50%">Additional objectclass name</td>
<td align="left" valign="top" width="20%">Input</td>
<td align="left" valign="top" width="20%">Char(*)</td>
</tr>
<tr>
<td align="center" valign="top" width="10%">9</td>
<td align="left" valign="top" width="50%">Length of additional objectclass name</td>
<td align="left" valign="top" width="20%">Input</td>
<td align="left" valign="top" width="20%">Binary(4)</td>
</tr>
<tr>
<td align="center" valign="top" width="10%">10</td>
<td align="left" valign="top" width="50%">Error code</td>
<td align="left" valign="top" width="20%">Input/Output</td>
<td align="left" valign="top" width="20%">Char(*)</td>
</tr>
</table>
<br>
&nbsp;&nbsp;Optional Parameter Group:<br>
<br>
<table width="100%">
<tr>
<td align="center" valign="top" width="10%">11</td>
<td align="left" valign="top" width="50%">Alternate CCSID</td>
<td align="left" valign="top" width="20%">Input</td>
<td align="left" valign="top" width="20%">Binary(4)</td>
</tr>
<tr>
<td align="center" valign="top" width="10%">12</td>
<td align="left" valign="top" width="50%">Entry Exists Action</td>
<td align="left" valign="top" width="20%">Input</td>
<td align="left" valign="top" width="20%">Char(1)</td>
</tr>
</table>
<br>
&nbsp;&nbsp;Default Public Authority: *USE<br>
<!-- iddvc RMBR -->
<br>
&nbsp;&nbsp;Threadsafe: Yes<br>
<!-- iddvc RMBR -->
<br>
</div>
<p>The <strong>Copy Validation List To Directory</strong> API copies internet
users defined in a validation list to the local IBM Directory Server. The API
creates <code>inetOrgPerson</code> directory entries with passwords based on
the original validation list entry. This API is intended to be used with
validation list entries created for use with the HTTP Server.</p>
<p>The API can copy only those validation list entries which do not correspond
to existing directory entries, or the API can be used to also update
the userpassword attribute of existing entries from the validation list, keeping
the directory entry passwords synchronized with the validation list.</p>
<p>Once the validation list entries have been copied into directory entries
there is no link between the two. Validation list entries and directory entries
can be added, changed, and deleted without affecting the other.</p>
<p>All entries in the validation list are copied to the directory server. If
only a subset of entries is wanted, a copy of the original validation list can
be used, containing only the entries of interest. The API can be run multiple
times copying the same validation list to the directory server.</p>
<p><strong>Notes:</strong></p>
<ol>
<li>When copying a validation list for which a corresponding directory entry
already exists, informational message GLD023B, Object for user &amp;1 already
exists, may be logged. Additionally, the directory server job log may contain
message GLD0401, Entry already exists.</li>
<li>Directory server password policy applies to the newly created entries with
the exception that the new entries will not be created with the password marked
as reset.</li>
<li>Validation lists may contain entries with CCSID values that are not valid even though the corresponding user names and passwords appear to work correctly in other applications.
These incorrect CCSIDs result in a diagnostic message, GLD023E - Error with &amp;1 value in validation list entry.
If this error occurs, this API can be used to copy these entries if the <a href="#ALTCCSID">Alternate CCSID</a> parameter is specified.
This parameter provides a CCSID to be used when validation list entries have CCSID values that are not valid.
The CCSID to use is typically the job CCSID of the application that uses the validation list.</li>
</ol>
<p>This API can be used as follows:</p>
<ul>
<li>The API can be called as one-time process to add a static set of internet
users to the IBM Directory Server. Once added to the directory, these users can
authenticate both to applications that use the validation list and to
applications using LDAP authentication. Because data is copied from the
validation list to the directory server, subsequent changes to either set of
users do not affect the other.</li>
<li>The API can be called periodically to add new internet users to the IBM
Directory Server. The API checks for existing entries and adds entries for
users that are not currently defined in the directory server. Passwords for existing
directory entries are optionally updated. Deletion of users from the validation list
is not detected; the corresponding directory entries will remain.</li>
<li>After copying the directory entries, the original applications can be
changed to use LDAP authentication, and the original validation list deleted,
or the validation list can be left on the system for continued use by other
applications.</li>
</ul>
<br>
<h3>Mapping of Validation List Entries to Directory Entries</h3>
<p>The validation list entries must be of the format used by HTTP Server internet users:</p>
<ul>
<li>The entry id contains the user name, tagged with a CCSID.</li>
<li>The entry data contains the comments.</li>
<li>The encrypted data contains the user password, tagged with a CCSID and one-way encrypted.</li>
</ul>
<p>
This information is mapped to a directory entry as follows:</p>
<table border width="80%">
<tr>
<td align="center" valign="top" width="50%"><strong>Attribute</strong></td>
<td align="center" valign="top" width="50%"><strong>Value</strong></td>
</tr>
<tr>
<td align="left" valign="top" width="50%">relative distinguished name</td>
<td align="left" valign="top" width="50%">uid=&lt;user name&gt;</td>
</tr>
<tr>
<td align="left" valign="top" width="50%">objectclass</td>
<td align="left" valign="top" width="50%">additional objectclass specified on API call plus inetOrgPerson, organizationalPerson, person, top</td>
</tr>
<tr>
<td align="left" valign="top" width="50%">uid</td>
<td align="left" valign="top" width="50%">&lt;user name&gt;</td>
</tr>
<tr>
<td align="left" valign="top" width="50%">cn</td>
<td align="left" valign="top" width="50%">&lt;user name&gt;</td>
</tr>
<tr>
<td align="left" valign="top" width="50%">sn</td>
<td align="left" valign="top" width="50%">&lt;user name&gt;</td>
</tr>
<tr>
<td align="left" valign="top" width="50%">description</td>
<td align="left" valign="top" width="50%">&lt;comments&gt;</td>
</tr>
<tr>
<td align="left" valign="top" width="50%">userpassword</td>
<td align="left" valign="top" width="50%">{VLDL}&lt;one way encrypted password data from validation list entry&gt;</td>
</tr>
</table>
<p>
For example, using the parent DN <code>cn=http users,o=my company</code>
and an internet user defined in the validation list MYLIB/HTTPVLDL:</p>
<pre>
user name: jsmith (CCSID 37)
comments: John Smith, dept ABC
password: ****** (CCSID 37)
</pre>
a directory entry would be created that looks like:
<pre>
dn: uid=jsmith,cn=http users,o=my company
objectclass: top
objectclass: person
objectclass: organizationalPerson
objectclass: inetOrgPerson
uid: jsmith
cn: jsmith
sn: jsmith
description: John Smith, dept ABC
userpassword: {VLDL}&lt;password data&gt;
</pre>
<br>
<p>The <strong>additional objectclass name</strong> parameter is used when you
want to create directory entries that use an objectclass other than the default
<strong>inetOrgPerson</strong> class. For example, you may have defined your
own structural or auxiliary objectclass that includes additional attributes you
want to be able to use with these entries. This API imposes the following
restrictions on the additional objectclass name:</p>
<ul>
<li>The objectclass must be a structural objectclass that inherits from
inetorgperson, or an auxiliary class.</li>
<li>The objectclass cannot have any required attributes other than those used
by this API: cn, sn, and uid.</li>
</ul>
<p>The newly created directory entry may be modified with the following
restrictions:</p>
<ul>
<li>The uid attribute must not be changed.</li>
</ul>
<p>Other attributes can be changed. For example, the cn and sn attributes can
be changed to contain the user's full name and last name respectively, and
other attributes, such as telephonenumber, can be added to the entry.</p>
<p>If the validation list users are to coexist with other users defined in the
directory server, consider creating a separate directory subtree to contain
validation list users. If multiple validation lists are being copied to the
directory server, you may want to use a separate subtree for each validation
list. If the validation list is being copied to initially populate the
directory, there is no reason to put the validation list users in a separate
subtree.</p>
<p>In either case, copy the validation list users to a location where they can
be used by the proper applications. For example, if you have existing
applications using LDAP authentication with users located in the subtree
<code>cn=users,o=my company</code>, you may want to create a subtree named
<code>cn=http users,cn=users,o=my company</code>. Alternatively, you could
create a subtree named <code>cn=http users,o=my company</code>, and reconfigure
your applications to look under <code>o=my company</code>, which will include
users located in both <code>cn=http users,o=my company</code> and
<code>cn=users,o=my company</code>. Other configurations are possible as
well.</p>
<p>Placing validation list users in a separate subtree(s) has the following
benefits:</p>
<ul>
<li>If different validation lists are used by different applications, the same
sets of users are easily carried over to LDAP authentication by configuring the
applications to use the appropriate directory subtree, for example:
<code>cn=application 1 users,o=my company</code> or <code>cn=application 2
users,o=my company</code>. You may be able to configure the application to use
groups for access control and define dynamic groups (groupOfUrls) with a group
member URL that contains only entries from a specific subtree:
<pre>
memberUrl: ldap:///cn=application%201%20users,o=my%20company
</pre>
Where %20 represents the space character (ASCII 0x20) in a URL.
<br>
<br>
</li>
<li>Use of different subtrees makes it easier to manage conflicts between users
from different validation lists and between users from validation lists and
existing LDAP users that have the same uid value. LDAP authentication typically
requires that exactly one entry match a given user name. Placing entries in
different subtrees makes it easier to determine where the conflicting entries
came from and to delete the proper entry if necessary.</li>
</ul>
<p>See <a href="#HDRCEEEX">Examples</a> for examples of calling this API from
the command line.</p>
<br>
<h3>Authorities and Locks</h3>
<dl>
<dt><em>Validation List Object</em></dt>
<dd>*CHG</dd>
<dt><em>Validation List Object Library</em></dt>
<dd>*EXECUTE</dd>
<dt><em>Directory server authorities</em></dt>
<dd>The bind distinguished name must have authority to add entries beneath the parent distinguished name.</dd>
</dl>
<br>
<h3>Required Parameter Group</h3>
<p><strong>Qualified validation list name</strong>
The name of the validation list and the library in which it resides.
The first 10 characters specify the validation list name and the second 10 characters specify the library.</p>
The following special value may be specified:
<table cellpadding="5">
<tr>
<td align="left" valign="top"><em>*CURLIB</em></td>
<td align="left" valign="top">The job's current library</td>
</tr>
<tr>
<td align="left" valign="top"><em>*LIBL</em></td>
<td align="left" valign="top">The library list</td>
</tr>
</table>
<p><strong>Bind distinguished name</strong>
Specifies the distinguished name used to authenticate to the directory server.
This parameter is specified in the default job CCSID.</p>
<p><strong>Length of bind distinguished name</strong>
The length, in bytes, of the <code>bind distinguished name</code> parameter.
The following special value may be specified:</p>
<table cellpadding="5">
<tr>
<td align="left" valign="top"><em>0</em></td>
<td align="left" valign="top">The <code>bind distinguished name</code> is a null-terminated string.</td>
</tr>
</table>
<p><strong>Bind password</strong>
Specifies the password for bind distinguished name.
This parameter is specified in the default job CCSID.</p>
<p><strong>Length of bind password</strong>
The length, in bytes, of the <code>bind password</code> parameter.
The following special value may be specified:</p>
<table cellpadding="5">
<tr>
<td align="left" valign="top"><em>0</em></td>
<td align="left" valign="top">The <code>bind password</code> is a null-terminated string.</td>
</tr>
</table>
<p><strong>Parent distinguished name</strong>
Specifies the parent distinguished name of the LDAP objects to be created.
This parameter is specified in the default job CCSID.</p>
<p><strong>Length of parent distinguished name</strong>
The length, in bytes, of the <code>parent distinguished name</code> parameter.
The following special value may be specified:</p>
<table cellpadding="5">
<tr>
<td align="left" valign="top"><em>0</em></td>
<td align="left" valign="top">The <code>parent distinguished name</code> is a null-terminated string.</td>
</tr>
</table>
<p><strong>Additional objectclass name</strong>
Specifies the name of an objectclass to be used when creating new directory entries.
Created entries will use this objectclass as well as <code>inetorgperson</code>, <code>organizationalPerson</code>, <code>person</code>, and <code>top</code>.
To use only the default objectclass, inetorgperson, specify a single null byte for this parameter and a length of 0.
This parameter is specified in the default job CCSID.</p>
<p><strong>Length of additional objectclass name</strong>
The length, in bytes, of the <code>additional objectclass name</code> parameter.
The following special value may be specified:</p>
<table cellpadding="5">
<tr>
<td align="left" valign="top"><em>0</em></td>
<td align="left" valign="top">The <code>additional objectclass name</code> is a null-terminated string.</td>
</tr>
</table>
<p><strong>Error code</strong>
The structure in which to return error information. For the format of the
structure, see <a href="../apiref/error.htm#hdrerrcod">Error Code Parameter</a>.</p>
<br>
<h3>Optional Parameter Group</h3>
<p><strong>Alternate CCSID</strong>
<a name="ALTCCSID"></a>Specifies the CCSID to be used for validation list entries which do not have a valid CCSID value.
The following values may be used:
<table cellpadding="5">
<tr>
<td align="left" valign="top"><em>-1</em></td>
<td align="left" valign="top">Report an error for validation list entries that do not have a valid CCSID value and continue with the next entry</td>
</tr>
<tr>
<td align="left" valign="top"><em>0</em></td>
<td align="left" valign="top">Use the default job CCSID for entries that do not have a valid CCSID value</td>
</tr>
<tr>
<td align="left" valign="top"><em>CCSID</em></td>
<td align="left" valign="top">Use the specified CCSID for entries that do not have a valid CCSID value</td>
</tr>
</table>
<p>
If this parameter is not specified, the default value is -1.
<br>
<p><strong>Entry Exists Action</strong>
<a name="ALTCCSID"></a>Specifies the action to take when a directory entry
corresponding to a validation list entry already exists.
The following values may be used:
<table cellpadding="5">
<tr>
<td align="left" valign="top"><em>'M'</em></td>
<td align="left" valign="top">Put a message in the job log identifying each entry that already exists in the directory.
The existing directory entry will be left unchanged</td>
</tr>
<tr>
<td align="left" valign="top"><em>'U'</em></td>
<td align="left" valign="top">Update existing entries to replace the 'userpassword' value with the password from the validation list entry</td>
</tr>
<tr>
<td align="left" valign="top"><em>'I'</em></td>
<td align="left" valign="top">Skip the validation list entry and continue processing.
No message will be put in the job log and the existing directory entry will be left unchanged</td>
</tr>
</table>
<p>
If this parameter is not specified, the default value is 'M'.
<br>
<h3><a name="header_9">Error Messages</a></h3>
<p>The following messages may be sent from this function:</p>
<table width="100%">
<tr>
<th align="left" valign="top">Message ID</th>
<th align="left" valign="top">Error Message Text</th>
</tr>
<tr>
<td valign="top">GLD0237</td>
<td valign="top">Directory Server is not started.</td>
</tr>
<tr>
<td valign="top">GLD0238</td>
<td valign="top">Bind distinguished name or password is not correct.</td>
</tr>
<tr>
<td valign="top">GLD0239</td>
<td valign="top">Parent object does not exist.</td>
</tr>
<tr>
<td valign="top">GLD023A</td>
<td valign="top">Not authorized to directory object.</td>
</tr>
<tr>
<td valign="top">GLD023C</td>
<td valign="top">Schema violation for entry '&amp;1'.</td>
</tr>
<tr>
<td valign="top">GLD023F</td>
<td valign="top">Error &amp;1 returned by API &amp;2.</td>
</tr>
<tr>
<td valign="top">GLD0240</td>
<td valign="top">LDAP error code &amp;1 returned by API &amp;2.</td>
</tr>
<tr>
<td valign="top">GLD0241</td>
<td valign="top">Errors occurred adding entries.</td>
</tr>
<tr>
<td valign="top">GLD0242</td>
<td valign="top">Error with &amp;1 value in validation list entry.</td>
</tr>
<tr>
<td valign="top">GLD0502</td>
<td valign="top">Error &amp;1 returned by API &amp;2.</td>
</tr>
<tr>
<td valign="top">CPF3CF1</td>
<td valign="top">Error code parameter not valid.</td>
</tr>
<tr>
<td valign="top">CPF3CF2</td>
<td valign="top">Error(s) occurred during running of &amp;1 API.</td>
</tr>
<tr>
<td valign="top">CPF3C36</td>
<td valign="top">Number of parameters, &amp;1, entered for this parameter was not valid.</td>
</tr>
<tr>
<td valign="top">CPF3C3A</td>
<td valign="top">Value for parameter &amp;2 for API &amp;1 not valid.</td>
</tr>
<tr>
<td valign="top">CPF9801</td>
<td valign="top">Object &amp;1 in &amp;2 type &amp;3 not found.</td>
</tr>
<tr>
<td valign="top">CPF9802</td>
<td valign="top">Not authorized to object &amp;1 in &amp;2 type &amp;3.</td>
</tr>
<tr>
<td valign="top">CPF9804</td>
<td valign="top">Object &amp;1 in &amp;2 type &amp;3 damaged.</td>
</tr>
<tr>
<td valign="top">CPFB617</td>
<td valign="top">CCSID not valid.</td>
</tr>
</table>
<br>
<br>
<h3><a name="HDRCEEEX">Examples</a></h3>
<p>See <a href="../apiref/aboutapis.htm#codedisclaimer">Code disclaimer information</a>
for information pertaining to code examples.</p>
<p><strong>Basic example</strong></p>
<p>Copy the validation list MYLIB/MYVLDL, authenticating to the directory server
as <code>cn=administrator</code> with a password of <code>secret</code>.
LDAP objects will be created under <code>cn=http users,o=my company</code> using
the default <code>inetorgperson</code> objectclass.
The API is called with null-terminated strings.</p>
<pre>
CALL PGM(QSYS/QGLDCPYVL) PARM('MYVLDL MYLIB ' 'cn=administrator' X'00000000'
'secret' X'00000000' 'cn=http users,o=my company,c=us' X'00000000' '' X'00000000' X'00000000')
</pre>
<br>
<p><strong>Example specifying an alternate CCSID</strong></p>
<p>This example is similar to the first example, except that the <code>Alternate CCSID</code> parameter is
used to specify that CCSID 278 be used for validation list entries that do not have valid CCSIDs.
The CCSID is specified as a hexadecimal value, where decimal 278 is hexadecimal 116. </p>
<pre>
CALL PGM(QSYS/QGLDCPYVL) PARM('MYVLDL MYLIB ' 'cn=administrator' X'00000000'
'secret' X'00000000' 'cn=http users,o=my company,c=us' X'00000000' '' X'00000000'
X'00000000' X'00000116')
</pre>
<br>
<p><strong>Example to update passwords from the validation list</strong></p>
<p>This example is similar to the first example, except that <code>Entry Exists Action</code>
parameter is used to specify that the password for existing entries be updated from the validation list.
The <code>Alternate CCSID</code> parameter is set to use the job CCSID.</p>
<pre>
CALL PGM(QSYS/QGLDCPYVL) PARM('MYVLDL MYLIB ' 'cn=administrator' X'00000000'
'secret' X'00000000' 'cn=http users,o=my company,c=us' X'00000000' '' X'00000000'
X'00000000' X'00000000' 'U')
</pre>
<br>
<img src="deltaend.gif" alt="End of change">
<hr>
API introduced: V5R4
<hr>
<center>
<table cellpadding="2" cellspacing="2">
<tr align="center">
<td valign="middle" align="center"><a href="#Top_Of_Page">Top</a> | <a href=
"dirserv1.htm">LDAP APIs</a> | <a href="aplist.htm">APIs by
category</a></td>
</tr>
</table>
</center>
</body>
</html>
Reference in New Issue Copy Permalink